docs/htmldocs/winbindd.8.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>winbindd</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"><a name="winbindd.8"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2>Name</h2><p>winbindd &#8212; Name Service Switch daemon for resolving names
   2         from NT servers</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><tt class="command">winbindd</tt>  [-F] [-S] [-i] [-B] [-d &lt;debug level&gt;] [-s &lt;smb config file&gt;] [-n]</p></div></div><div class="refsect1" lang="en"><h2>DESCRIPTION</h2><p>This program is part of the <a href="Samba.7.html"><span class="citerefentry"><span class="refentrytitle">Samba</span>(7)</span></a> suite.</p><p><b class="command">winbindd</b> is a daemon that provides
   3         a service for the Name Service Switch capability that is present
   4         in most modern C libraries.  The Name Service Switch allows user
   5         and system information to be obtained from different databases
   6         services such as NIS or DNS.  The exact behaviour can be configured
   7         throught the <tt class="filename">/etc/nsswitch.conf</tt> file.
   8         Users and groups are allocated as they are resolved to a range
   9         of user and group ids specified by the administrator of the
  10         Samba system.</p><p>The service provided by <b class="command">winbindd</b> is called `winbind' and
  11         can be used to resolve user and group information from a
  12         Windows NT server. The service can also provide authentication
  13         services via an associated PAM module. </p><p>
  14         The <tt class="filename">pam_winbind</tt> module in the 2.2.2 release only
  15         supports the <i class="parameter"><tt>auth</tt></i> and <i class="parameter"><tt>account</tt></i>
  16         module-types.  The latter simply
  17         performs a getpwnam() to verify that the system can obtain a uid for the
  18         user.  If the <tt class="filename">libnss_winbind</tt> library has been correctly
  19         installed, this should always succeed.
  20         </p><p>The following nsswitch databases are implemented by
  21         the winbindd service: </p><div class="variablelist"><dl><dt><span class="term">hosts</span></dt><dd><p>User information traditionally stored in
  22                 the <tt class="filename">hosts(5)</tt> file and used by
  23                 <b class="command">gethostbyname(3)</b> functions. Names are
  24                 resolved through the WINS server or by broadcast.
  25                 </p></dd><dt><span class="term">passwd</span></dt><dd><p>User information traditionally stored in
  26                 the <tt class="filename">passwd(5)</tt> file and used by
  27                 <b class="command">getpwent(3)</b> functions. </p></dd><dt><span class="term">group</span></dt><dd><p>Group information traditionally stored in
  28                 the <tt class="filename">group(5)</tt> file and used by
  29                 <b class="command">getgrent(3)</b> functions. </p></dd></dl></div><p>For example, the following simple configuration in the
  30         <tt class="filename">/etc/nsswitch.conf</tt> file can be used to initially
  31         resolve user and group information from <tt class="filename">/etc/passwd
  32         </tt> and <tt class="filename">/etc/group</tt> and then from the
  33         Windows NT server.
  34 </p><pre class="programlisting">
  35 passwd:         files winbind
  36 group:          files winbind
  37 </pre><p>The following simple configuration in the
  38         <tt class="filename">/etc/nsswitch.conf</tt> file can be used to initially
  39         resolve hostnames from <tt class="filename">/etc/hosts</tt> and then from the
  40         WINS server.</p></div><div class="refsect1" lang="en"><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">-F</span></dt><dd><p>If specified, this parameter causes
  41                 the main <b class="command">winbindd</b> process to not daemonize,
  42                 i.e. double-fork and disassociate with the terminal.
  43                 Child processes are still created as normal to service
  44                 each connection request, but the main process does not
  45                 exit. This operation mode is suitable for running
  46                 <b class="command">winbindd</b> under process supervisors such
  47                 as <b class="command">supervise</b> and <b class="command">svscan</b>
  48                 from Daniel J. Bernstein's <b class="command">daemontools</b>
  49                 package, or the AIX process monitor.
  50                 </p></dd><dt><span class="term">-S</span></dt><dd><p>If specified, this parameter causes
  51                 <b class="command">winbindd</b> to log to standard output rather
  52                 than a file.</p></dd><dt><span class="term">-V</span></dt><dd><p>Prints the version number for
  53 <b class="command">smbd</b>.</p></dd><dt><span class="term">-s &lt;configuration file&gt;</span></dt><dd><p>The file specified contains the
  54 configuration details required by the server.  The
  55 information in this file includes server-specific
  56 information such as what printcap file to use, as well
  57 as descriptions of all the services that the server is
  58 to provide. See <a href="smb.conf.5.html" target="_top"><tt class="filename">
  59 smb.conf(5)</tt></a> for more information.
  60 The default configuration file name is determined at
  61 compile time.</p></dd><dt><span class="term">-d|--debug=debuglevel</span></dt><dd><p><i class="replaceable"><tt>debuglevel</tt></i> is an integer
  62 from 0 to 10.  The default value if this parameter is
  63 not specified is zero.</p><p>The higher this value, the more detail will be
  64 logged to the log files about the activities of the
  65 server. At level 0, only critical errors and serious
  66 warnings will be logged. Level 1 is a reasonable level for
  67 day to day running - it generates a small amount of
  68 information about operations carried out.</p><p>Levels above 1 will generate considerable
  69 amounts of log data, and should only be used when
  70 investigating a problem. Levels above 3 are designed for
  71 use only by developers and generate HUGE amounts of log
  72 data, most of which is extremely cryptic.</p><p>Note that specifying this parameter here will
  73 override the <a href="smb.conf.5.html#loglevel" target="_top">log
  74 level</a> parameter in the <a href="smb.conf.5.html" target="_top">
  75 <tt class="filename">smb.conf(5)</tt></a> file.</p></dd><dt><span class="term">-l|--logfile=logbasename</span></dt><dd><p>File name for log/debug files. The extension
  76 <tt class="constant">&quot;.client&quot;</tt> will be appended. The log file is
  77 never removed by the client.
  78 </p></dd><dt><span class="term">-h|--help</span></dt><dd><p>Print a summary of command line options.
  79 </p></dd><dt><span class="term">-i</span></dt><dd><p>Tells <b class="command">winbindd</b> to not
  80                 become a daemon and detach from the current terminal. This
  81                 option is used by developers when interactive debugging
  82                 of <b class="command">winbindd</b> is required.
  83                 <b class="command">winbindd</b> also logs to standard output,
  84                 as if the <b class="command">-S</b> parameter had been given.
  85                 </p></dd><dt><span class="term">-n</span></dt><dd><p>Disable caching. This means winbindd will
  86                 always have to wait for a response from the domain controller
  87                 before it can respond to a client and this thus makes things
  88                 slower. The results will however be more accurate, since
  89                 results from the cache might not be up-to-date. This
  90                 might also temporarily hang winbindd if the DC doesn't respond.
  91                 </p></dd><dt><span class="term">-B</span></dt><dd><p>Dual daemon mode. This means winbindd will run
  92                 as 2 threads. The first will answer all requests from the cache,
  93                 thus making responses to clients faster. The other will
  94                 update the cache for the query that the first has just responded.
  95                 Advantage of this is that responses stay accurate and are faster.
  96                 </p></dd></dl></div></div><div class="refsect1" lang="en"><h2>NAME AND ID RESOLUTION</h2><p>Users and groups on a Windows NT server are assigned
  97         a relative id (rid) which is unique for the domain when the
  98         user or group is created.  To convert the Windows NT user or group
  99         into a unix user or group, a mapping between rids and unix user
 100         and group ids is required.  This is one of the jobs that <b class="command">
 101         winbindd</b> performs. </p><p>As winbindd users and groups are resolved from a server, user
 102         and group ids are allocated from a specified range.  This
 103         is done on a first come, first served basis, although all existing
 104         users and groups will be mapped as soon as a client performs a user
 105         or group enumeration command.  The allocated unix ids are stored
 106         in a database file under the Samba lock directory and will be
 107         remembered. </p><p>WARNING: The rid to unix id database is the only location
 108         where the user and group mappings are stored by winbindd.  If this
 109         file is deleted or corrupted, there is no way for winbindd to
 110         determine which user and group ids correspond to Windows NT user
 111         and group rids. </p></div><div class="refsect1" lang="en"><h2>CONFIGURATION</h2><p>Configuration of the <b class="command">winbindd</b> daemon
 112         is done through configuration parameters in the <a href="smb.conf.5.html"><span class="citerefentry"><span class="refentrytitle">smb.conf</span>(5)</span></a> file.  All parameters should be specified in the
 113         [global] section of smb.conf. </p><div class="itemizedlist"><ul type="disc"><li><p><a href="smb.conf.5.html#WINBINDSEPARATOR" target="_top">
 114                 <i class="parameter"><tt>winbind separator</tt></i></a></p></li><li><p><a href="smb.conf.5.html#WINBINDUID" target="_top">
 115                 <i class="parameter"><tt>winbind uid</tt></i></a></p></li><li><p><a href="smb.conf.5.html#WINBINDGID" target="_top">
 116                 <i class="parameter"><tt>winbind gid</tt></i></a></p></li><li><p><a href="smb.conf.5.html#WINBINDCACHETIME" target="_top">
 117                 <i class="parameter"><tt>winbind cache time</tt></i></a></p></li><li><p><a href="smb.conf.5.html#WINBINDENUMUSERS" target="_top">
 118                 <i class="parameter"><tt>winbind enum users</tt></i></a></p></li><li><p><a href="smb.conf.5.html#WINBINDENUMGROUPS" target="_top">
 119                 <i class="parameter"><tt>winbind enum groups</tt></i></a></p></li><li><p><a href="smb.conf.5.html#TEMPLATEHOMEDIR" target="_top">
 120                 <i class="parameter"><tt>template homedir</tt></i></a></p></li><li><p><a href="smb.conf.5.html#TEMPLATESHELL" target="_top">
 121                 <i class="parameter"><tt>template shell</tt></i></a></p></li><li><p><a href="smb.conf.5.html#WINBINDUSEDEFAULTDOMAIN" target="_top">
 122                 <i class="parameter"><tt>winbind use default domain</tt></i></a></p></li></ul></div></div><div class="refsect1" lang="en"><h2>EXAMPLE SETUP</h2><p>To setup winbindd for user and group lookups plus
 123         authentication from a domain controller use something like the
 124         following setup. This was tested on a RedHat 6.2 Linux box. </p><p>In <tt class="filename">/etc/nsswitch.conf</tt> put the
 125         following:
 126 </p><pre class="programlisting">
 127 passwd:     files winbind
 128 group:      files winbind
 129 </pre><p>In <tt class="filename">/etc/pam.d/*</tt> replace the <i class="parameter"><tt>
 130         auth</tt></i> lines with something like this:
 131 </p><pre class="programlisting">
 132 auth       required     /lib/security/pam_securetty.so
 133 auth       required     /lib/security/pam_nologin.so
 134 auth       sufficient   /lib/security/pam_winbind.so
 135 auth       required     /lib/security/pam_pwdb.so use_first_pass shadow nullok
 136 </pre><p>Note in particular the use of the <i class="parameter"><tt>sufficient
 137         </tt></i> keyword and the <i class="parameter"><tt>use_first_pass</tt></i> keyword. </p><p>Now replace the account lines with this: </p><p><b class="command">account    required       /lib/security/pam_winbind.so
 138         </b></p><p>The next step is to join the domain. To do that use the
 139         <b class="command">net</b> program like this:  </p><p><b class="command">net join -S PDC -U Administrator</b></p><p>The username after the <i class="parameter"><tt>-U</tt></i> can be any
 140         Domain user that has administrator privileges on the machine.
 141         Substitute the name or IP of your PDC for &quot;PDC&quot;.</p><p>Next copy <tt class="filename">libnss_winbind.so</tt> to
 142         <tt class="filename">/lib</tt> and <tt class="filename">pam_winbind.so
 143         </tt> to <tt class="filename">/lib/security</tt>.  A symbolic link needs to be
 144         made from <tt class="filename">/lib/libnss_winbind.so</tt> to
 145         <tt class="filename">/lib/libnss_winbind.so.2</tt>.  If you are using an
 146         older version of glibc then the target of the link should be
 147         <tt class="filename">/lib/libnss_winbind.so.1</tt>.</p><p>Finally, setup a <a href="smb.conf.5.html"><span class="citerefentry"><span class="refentrytitle">smb.conf</span>(5)</span></a> containing directives like the
 148         following:
 149 </p><pre class="programlisting">
 150 [global]
 151         winbind separator = +
 152         winbind cache time = 10
 153         template shell = /bin/bash
 154         template homedir = /home/%D/%U
 155         winbind uid = 10000-20000
 156         winbind gid = 10000-20000
 157         workgroup = DOMAIN
 158         security = domain
 159         password server = *
 160 </pre><p>Now start winbindd and you should find that your user and
 161         group database is expanded to include your NT users and groups,
 162         and that you can login to your unix box as a domain user, using
 163         the DOMAIN+user syntax for the username. You may wish to use the
 164         commands <b class="command">getent passwd</b> and <b class="command">getent group
 165         </b> to confirm the correct operation of winbindd.</p></div><div class="refsect1" lang="en"><h2>NOTES</h2><p>The following notes are useful when configuring and
 166         running <b class="command">winbindd</b>: </p><p><a href="nmbd.8.html"><span class="citerefentry"><span class="refentrytitle">nmbd</span>(8)</span></a> must be running on the local machine
 167         for <b class="command">winbindd</b> to work. <b class="command">winbindd</b> queries
 168         the list of trusted domains for the Windows NT server
 169         on startup and when a SIGHUP is received.  Thus, for a running <b class="command">
 170         winbindd</b> to become aware of new trust relationships between
 171         servers, it must be sent a SIGHUP signal. </p><p>PAM is really easy to misconfigure.  Make sure you know what
 172         you are doing when modifying PAM configuration files.  It is possible
 173         to set up PAM such that you can no longer log into your system. </p><p>If more than one UNIX machine is running <b class="command">winbindd</b>,
 174         then in general the user and groups ids allocated by winbindd will not
 175         be the same.  The user and group ids will only be valid for the local
 176         machine.</p><p>If the the Windows NT RID to UNIX user and group id mapping
 177         file is damaged or destroyed then the mappings will be lost. </p></div><div class="refsect1" lang="en"><h2>SIGNALS</h2><p>The following signals can be used to manipulate the
 178         <b class="command">winbindd</b> daemon. </p><div class="variablelist"><dl><dt><span class="term">SIGHUP</span></dt><dd><p>Reload the <a href="smb.conf.5.html"><span class="citerefentry"><span class="refentrytitle">smb.conf</span>(5)</span></a> file and
 179                 apply any parameter changes to the running
 180                 version of winbindd.  This signal also clears any cached
 181                 user and group information.  The list of other domains trusted
 182                 by winbindd is also reloaded.  </p></dd><dt><span class="term">SIGUSR1</span></dt><dd><p>The SIGUSR1 signal will cause <b class="command">
 183                 winbindd</b> to write status information to the winbind
 184                 log file including information about the number of user and
 185                 group ids allocated by <b class="command">winbindd</b>.</p><p>Log files are stored in the filename specified by the
 186                 log file parameter.</p></dd></dl></div></div><div class="refsect1" lang="en"><h2>FILES</h2><div class="variablelist"><dl><dt><span class="term"><tt class="filename">/etc/nsswitch.conf(5)</tt></span></dt><dd><p>Name service switch configuration file.</p></dd><dt><span class="term">/tmp/.winbindd/pipe</span></dt><dd><p>The UNIX pipe over which clients communicate with
 187                 the <b class="command">winbindd</b> program.  For security reasons, the
 188                 winbind client will only attempt to connect to the winbindd daemon
 189                 if both the <tt class="filename">/tmp/.winbindd</tt> directory
 190                 and <tt class="filename">/tmp/.winbindd/pipe</tt> file are owned by
 191                 root. </p></dd><dt><span class="term">$LOCKDIR/winbindd_privilaged/pipe</span></dt><dd><p>The UNIX pipe over which 'privilaged' clients
 192                 communicate with the <b class="command">winbindd</b> program.  For security
 193                 reasons, access to some winbindd functions - like those needed by
 194                 the <b class="command">ntlm_auth</b> utility - is restricted.  By default,
 195                 only users in the 'root' group will get this access, however the administrator
 196                 may change the group permissions on $LOCKDIR/winbindd_privilaged to allow
 197                 programs like 'squid' to use ntlm_auth.
 198                 Note that the winbind client will only attempt to connect to the winbindd daemon
 199                 if both the <tt class="filename">$LOCKDIR/winbindd_privilaged</tt> directory
 200                 and <tt class="filename">$LOCKDIR/winbindd_privilaged/pipe</tt> file are owned by
 201                 root. </p></dd><dt><span class="term">/lib/libnss_winbind.so.X</span></dt><dd><p>Implementation of name service switch library.
 202                 </p></dd><dt><span class="term">$LOCKDIR/winbindd_idmap.tdb</span></dt><dd><p>Storage for the Windows NT rid to UNIX user/group
 203                 id mapping.  The lock directory is specified when Samba is initially
 204                 compiled using the <i class="parameter"><tt>--with-lockdir</tt></i> option.
 205                 This directory is by default <tt class="filename">/usr/local/samba/var/locks
 206                 </tt>. </p></dd><dt><span class="term">$LOCKDIR/winbindd_cache.tdb</span></dt><dd><p>Storage for cached user and group information.
 207                 </p></dd></dl></div></div><div class="refsect1" lang="en"><h2>VERSION</h2><p>This man page is correct for version 3.0 of
 208         the Samba suite.</p></div><div class="refsect1" lang="en"><h2>SEE ALSO</h2><p><tt class="filename">nsswitch.conf(5)</tt>, <a href="Samba.7.html"><span class="citerefentry"><span class="refentrytitle">Samba</span>(7)</span></a>, <a href="wbinfo.8.html"><span class="citerefentry"><span class="refentrytitle">wbinfo</span>(8)</span></a>, <a href="smb.conf.5.html"><span class="citerefentry"><span class="refentrytitle">smb.conf</span>(5)</span></a></p></div><div class="refsect1" lang="en"><h2>AUTHOR</h2><p>The original Samba software and related utilities
 209         were created by Andrew Tridgell. Samba is now developed
 210         by the Samba Team as an Open Source project similar
 211         to the way the Linux kernel is developed.</p><p><b class="command">wbinfo</b> and <b class="command">winbindd</b> were
 212         written by Tim Potter.</p><p>The conversion to DocBook for Samba 2.2 was done
 213         by Gerald Carter. The conversion to DocBook XML 4.2 for
 214         Samba 3.0 was done by Alexander Bokovoy.</p></div></div></body></html>