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] [-Y] [-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 program version number.
  53 </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 <tt class="filename">smb.conf</tt> for more information.
  59 The default configuration file name is determined at
  60 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
  61 from 0 to 10.  The default value if this parameter is
  62 not specified is zero.</p><p>The higher this value, the more detail will be
  63 logged to the log files about the activities of the
  64 server. At level 0, only critical errors and serious
  65 warnings will be logged. Level 1 is a reasonable level for
  66 day-to-day running - it generates a small amount of
  67 information about operations carried out.</p><p>Levels above 1 will generate considerable
  68 amounts of log data, and should only be used when
  69 investigating a problem. Levels above 3 are designed for
  70 use only by developers and generate HUGE amounts of log
  71 data, most of which is extremely cryptic.</p><p>Note that specifying this parameter here will
  72 override the <a class="indexterm" name="id2796670"></a><i class="parameter"><tt>log level</tt></i> parameter
  73 in the <tt class="filename">smb.conf</tt> file.</p></dd><dt><span class="term">-l|--logfile=logbasename</span></dt><dd><p>File name for log/debug files. The extension
  74 <tt class="constant">".client"</tt> will be appended. The log file is
  75 never removed by the client.
  76 </p></dd><dt><span class="term">-h|--help</span></dt><dd><p>Print a summary of command line options.
  77 </p></dd><dt><span class="term">-i</span></dt><dd><p>Tells <b class="command">winbindd</b> to not
  78                 become a daemon and detach from the current terminal. This
  79                 option is used by developers when interactive debugging
  80                 of <b class="command">winbindd</b> is required.
  81                 <b class="command">winbindd</b> also logs to standard output,
  82                 as if the <b class="command">-S</b> parameter had been given.
  83                 </p></dd><dt><span class="term">-n</span></dt><dd><p>Disable caching. This means winbindd will
  84                 always have to wait for a response from the domain controller
  85                 before it can respond to a client and this thus makes things
  86                 slower. The results will however be more accurate, since
  87                 results from the cache might not be up-to-date. This
  88                 might also temporarily hang winbindd if the DC doesn't respond.
  89                 </p></dd><dt><span class="term">-Y</span></dt><dd><p>Single daemon mode. This means winbindd will run
  90                 as a single process (the mode of operation in Samba 2.2).  Winbindd's
  91                 default behavior is to launch a child process that is responsible for
  92                 updating expired cache entries.
  93                 </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
  94         a relative id (rid) which is unique for the domain when the
  95         user or group is created.  To convert the Windows NT user or group
  96         into a unix user or group, a mapping between rids and unix user
  97         and group ids is required.  This is one of the jobs that <b class="command">
  98         winbindd</b> performs. </p><p>As winbindd users and groups are resolved from a server, user
  99         and group ids are allocated from a specified range.  This
 100         is done on a first come, first served basis, although all existing
 101         users and groups will be mapped as soon as a client performs a user
 102         or group enumeration command.  The allocated unix ids are stored
 103         in a database file under the Samba lock directory and will be
 104         remembered. </p><p>WARNING: The rid to unix id database is the only location
 105         where the user and group mappings are stored by winbindd.  If this
 106         file is deleted or corrupted, there is no way for winbindd to
 107         determine which user and group ids correspond to Windows NT user
 108         and group rids. </p></div><div class="refsect1" lang="en"><h2>CONFIGURATION</h2><p>Configuration of the <b class="command">winbindd</b> daemon
 109         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
 110         [global] section of smb.conf. </p><div class="itemizedlist"><ul type="disc"><li><p>
 111                 <a class="indexterm" name="id2799169"></a><i class="parameter"><tt>winbind separator</tt></i></p></li><li><p>
 112                 <a class="indexterm" name="id2799187"></a><i class="parameter"><tt>idmap uid</tt></i></p></li><li><p>
 113                 <a class="indexterm" name="id2799205"></a><i class="parameter"><tt>idmap gid</tt></i></p></li><li><p>
 114                 <a class="indexterm" name="id2799223"></a><i class="parameter"><tt>winbind cache time</tt></i></p></li><li><p>
 115                 <a class="indexterm" name="id2799241"></a><i class="parameter"><tt>winbind enum users</tt></i></p></li><li><p>
 116                 <a class="indexterm" name="id2799259"></a><i class="parameter"><tt>winbind enum groups</tt></i></p></li><li><p>
 117                 <a class="indexterm" name="id2799277"></a><i class="parameter"><tt>template homedir</tt></i></p></li><li><p>
 118                 <a class="indexterm" name="id2799295"></a><i class="parameter"><tt>template shell</tt></i></p></li><li><p>
 119                 <a class="indexterm" name="id2799313"></a><i class="parameter"><tt>winbind use default domain</tt></i></p></li></ul></div></div><div class="refsect1" lang="en"><h2>EXAMPLE SETUP</h2><p>To setup winbindd for user and group lookups plus
 120         authentication from a domain controller use something like the
 121         following setup. This was tested on a RedHat 6.2 Linux box. </p><p>In <tt class="filename">/etc/nsswitch.conf</tt> put the
 122         following:
 123 </p><pre class="programlisting">
 124 passwd:     files winbind
 125 group:      files winbind
 126 </pre><p>In <tt class="filename">/etc/pam.d/*</tt> replace the <i class="parameter"><tt>
 127         auth</tt></i> lines with something like this:
 128 </p><pre class="programlisting">
 129 auth       required     /lib/security/pam_securetty.so
 130 auth       required     /lib/security/pam_nologin.so
 131 auth       sufficient   /lib/security/pam_winbind.so
 132 auth       required     /lib/security/pam_pwdb.so use_first_pass shadow nullok
 133 </pre><p>Note in particular the use of the <i class="parameter"><tt>sufficient
 134         </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
 135         </b></p><p>The next step is to join the domain. To do that use the
 136         <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
 137         Domain user that has administrator privileges on the machine.
 138         Substitute the name or IP of your PDC for "PDC".</p><p>Next copy <tt class="filename">libnss_winbind.so</tt> to
 139         <tt class="filename">/lib</tt> and <tt class="filename">pam_winbind.so
 140         </tt> to <tt class="filename">/lib/security</tt>.  A symbolic link needs to be
 141         made from <tt class="filename">/lib/libnss_winbind.so</tt> to
 142         <tt class="filename">/lib/libnss_winbind.so.2</tt>.  If you are using an
 143         older version of glibc then the target of the link should be
 144         <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
 145         following:
 146 </p><pre class="programlisting">
 147 [global]
 148         winbind separator = +
 149         winbind cache time = 10
 150         template shell = /bin/bash
 151         template homedir = /home/%D/%U
 152         idmap uid = 10000-20000
 153         idmap gid = 10000-20000
 154         workgroup = DOMAIN
 155         security = domain
 156         password server = *
 157 </pre><p>Now start winbindd and you should find that your user and
 158         group database is expanded to include your NT users and groups,
 159         and that you can login to your unix box as a domain user, using
 160         the DOMAIN+user syntax for the username. You may wish to use the
 161         commands <b class="command">getent passwd</b> and <b class="command">getent group
 162         </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
 163         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
 164         for <b class="command">winbindd</b> to work. <b class="command">winbindd</b> queries
 165         the list of trusted domains for the Windows NT server
 166         on startup and when a SIGHUP is received.  Thus, for a running <b class="command">
 167         winbindd</b> to become aware of new trust relationships between
 168         servers, it must be sent a SIGHUP signal. </p><p>PAM is really easy to misconfigure.  Make sure you know what
 169         you are doing when modifying PAM configuration files.  It is possible
 170         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>,
 171         then in general the user and groups ids allocated by winbindd will not
 172         be the same.  The user and group ids will only be valid for the local
 173         machine.</p><p>If the the Windows NT RID to UNIX user and group id mapping
 174         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
 175         <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
 176                 apply any parameter changes to the running
 177                 version of winbindd.  This signal also clears any cached
 178                 user and group information.  The list of other domains trusted
 179                 by winbindd is also reloaded.  </p></dd><dt><span class="term">SIGUSR2</span></dt><dd><p>The SIGUSR2 signal will cause <b class="command">
 180                 winbindd</b> to write status information to the winbind
 181                 log file including information about the number of user and
 182                 group ids allocated by <b class="command">winbindd</b>.</p><p>Log files are stored in the filename specified by the
 183                 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
 184                 the <b class="command">winbindd</b> program.  For security reasons, the
 185                 winbind client will only attempt to connect to the winbindd daemon
 186                 if both the <tt class="filename">/tmp/.winbindd</tt> directory
 187                 and <tt class="filename">/tmp/.winbindd/pipe</tt> file are owned by
 188                 root. </p></dd><dt><span class="term">$LOCKDIR/winbindd_privilaged/pipe</span></dt><dd><p>The UNIX pipe over which 'privilaged' clients
 189                 communicate with the <b class="command">winbindd</b> program.  For security
 190                 reasons, access to some winbindd functions - like those needed by
 191                 the <b class="command">ntlm_auth</b> utility - is restricted.  By default,
 192                 only users in the 'root' group will get this access, however the administrator
 193                 may change the group permissions on $LOCKDIR/winbindd_privilaged to allow
 194                 programs like 'squid' to use ntlm_auth.
 195                 Note that the winbind client will only attempt to connect to the winbindd daemon
 196                 if both the <tt class="filename">$LOCKDIR/winbindd_privilaged</tt> directory
 197                 and <tt class="filename">$LOCKDIR/winbindd_privilaged/pipe</tt> file are owned by
 198                 root. </p></dd><dt><span class="term">/lib/libnss_winbind.so.X</span></dt><dd><p>Implementation of name service switch library.
 199                 </p></dd><dt><span class="term">$LOCKDIR/winbindd_idmap.tdb</span></dt><dd><p>Storage for the Windows NT rid to UNIX user/group
 200                 id mapping.  The lock directory is specified when Samba is initially
 201                 compiled using the <i class="parameter"><tt>--with-lockdir</tt></i> option.
 202                 This directory is by default <tt class="filename">/usr/local/samba/var/locks
 203                 </tt>. </p></dd><dt><span class="term">$LOCKDIR/winbindd_cache.tdb</span></dt><dd><p>Storage for cached user and group information.
 204                 </p></dd></dl></div></div><div class="refsect1" lang="en"><h2>VERSION</h2><p>This man page is correct for version 3.0 of
 205         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
 206         were created by Andrew Tridgell. Samba is now developed
 207         by the Samba Team as an Open Source project similar
 208         to the way the Linux kernel is developed.</p><p><b class="command">wbinfo</b> and <b class="command">winbindd</b> were
 209         written by Tim Potter.</p><p>The conversion to DocBook for Samba 2.2 was done
 210         by Gerald Carter. The conversion to DocBook XML 4.2 for
 211         Samba 3.0 was done by Alexander Bokovoy.</p></div></div></body></html>