release/src/router/samba3/docs/htmldocs/manpages/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.70.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 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><code class="command">winbindd</code>  [-F] [-S] [-i] [-Y] [-d &lt;debug level&gt;] [-s &lt;smb config file&gt;] [-n]</p></div></div><div class="refsect1" lang="en"><a name="id2526334"></a><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><span><strong class="command">winbindd</strong></span> is a daemon that provides
   3         a number of services to the Name Service Switch capability found
   4         in most modern C libraries, to arbitary applications via PAM
   5         and <span><strong class="command">ntlm_auth</strong></span> and to Samba itself.</p><p>Even if winbind is not used for nsswitch, it still provides a
   6     service to <span><strong class="command">smbd</strong></span>, <span><strong class="command">ntlm_auth</strong></span>
   7     and the <span><strong class="command">pam_winbind.so</strong></span> PAM module, by managing connections to
   8     domain controllers.  In this configuraiton the
   9     <a class="indexterm" name="id2488089"></a>idmap uid and
  10     <a class="indexterm" name="id2488096"></a>idmap gid
  11     parameters are not required. (This is known as `netlogon proxy only mode'.)</p><p> The Name Service Switch allows user
  12         and system information to be obtained from different databases
  13         services such as NIS or DNS.  The exact behaviour can be configured
  14         throught the <code class="filename">/etc/nsswitch.conf</code> file.
  15         Users and groups are allocated as they are resolved to a range
  16         of user and group ids specified by the administrator of the
  17         Samba system.</p><p>The service provided by <span><strong class="command">winbindd</strong></span> is called `winbind' and
  18         can be used to resolve user and group information from a
  19         Windows NT server. The service can also provide authentication
  20         services via an associated PAM module. </p><p>
  21         The <code class="filename">pam_winbind</code> module supports the
  22         <em class="parameter"><code>auth</code></em>, <em class="parameter"><code>account</code></em>
  23         and <em class="parameter"><code>password</code></em>
  24         module-types.  It should be noted that the
  25         <em class="parameter"><code>account</code></em> module simply performs a getpwnam() to verify that
  26         the system can obtain a uid for the user, as the domain
  27         controller has already performed access control.  If the
  28         <code class="filename">libnss_winbind</code> library has been correctly
  29         installed, or an alternate source of names configured, this should always succeed.
  30         </p><p>The following nsswitch databases are implemented by
  31         the winbindd service: </p><div class="variablelist"><dl><dt><span class="term">hosts</span></dt><dd><p>This feature is only available on IRIX.
  32                 User information traditionally stored in
  33                 the <code class="filename">hosts(5)</code> file and used by
  34                 <span><strong class="command">gethostbyname(3)</strong></span> functions. Names are
  35                 resolved through the WINS server or by broadcast.
  36                 </p></dd><dt><span class="term">passwd</span></dt><dd><p>User information traditionally stored in
  37                 the <code class="filename">passwd(5)</code> file and used by
  38                 <span><strong class="command">getpwent(3)</strong></span> functions. </p></dd><dt><span class="term">group</span></dt><dd><p>Group information traditionally stored in
  39                 the <code class="filename">group(5)</code> file and used by
  40                 <span><strong class="command">getgrent(3)</strong></span> functions. </p></dd></dl></div><p>For example, the following simple configuration in the
  41         <code class="filename">/etc/nsswitch.conf</code> file can be used to initially
  42         resolve user and group information from <code class="filename">/etc/passwd
  43         </code> and <code class="filename">/etc/group</code> and then from the
  44         Windows NT server.
  45 </p><pre class="programlisting">
  46 passwd:         files winbind
  47 group:          files winbind
  48 ## only available on IRIX; Linux users should us libnss_wins.so
  49 hosts:          files dns winbind
  50 </pre><p>The following simple configuration in the
  51         <code class="filename">/etc/nsswitch.conf</code> file can be used to initially
  52         resolve hostnames from <code class="filename">/etc/hosts</code> and then from the
  53         WINS server.</p><pre class="programlisting">
  54 hosts:          files wins
  55 </pre></div><div class="refsect1" lang="en"><a name="id2488391"></a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">-F</span></dt><dd><p>If specified, this parameter causes
  56                 the main <span><strong class="command">winbindd</strong></span> process to not daemonize,
  57                 i.e. double-fork and disassociate with the terminal.
  58                 Child processes are still created as normal to service
  59                 each connection request, but the main process does not
  60                 exit. This operation mode is suitable for running
  61                 <span><strong class="command">winbindd</strong></span> under process supervisors such
  62                 as <span><strong class="command">supervise</strong></span> and <span><strong class="command">svscan</strong></span>
  63                 from Daniel J. Bernstein's <span><strong class="command">daemontools</strong></span>
  64                 package, or the AIX process monitor.
  65                 </p></dd><dt><span class="term">-S</span></dt><dd><p>If specified, this parameter causes
  66                 <span><strong class="command">winbindd</strong></span> to log to standard output rather
  67                 than a file.</p></dd><dt><span class="term">-V</span></dt><dd><p>Prints the program version number.
  68 </p></dd><dt><span class="term">-s &lt;configuration file&gt;</span></dt><dd><p>The file specified contains the
  69 configuration details required by the server.  The
  70 information in this file includes server-specific
  71 information such as what printcap file to use, as well
  72 as descriptions of all the services that the server is
  73 to provide. See <code class="filename">smb.conf</code> for more information.
  74 The default configuration file name is determined at
  75 compile time.</p></dd><dt><span class="term">-d|--debuglevel=level</span></dt><dd><p><em class="replaceable"><code>level</code></em> is an integer
  76 from 0 to 10.  The default value if this parameter is
  77 not specified is zero.</p><p>The higher this value, the more detail will be
  78 logged to the log files about the activities of the
  79 server. At level 0, only critical errors and serious
  80 warnings will be logged. Level 1 is a reasonable level for
  81 day-to-day running - it generates a small amount of
  82 information about operations carried out.</p><p>Levels above 1 will generate considerable
  83 amounts of log data, and should only be used when
  84 investigating a problem. Levels above 3 are designed for
  85 use only by developers and generate HUGE amounts of log
  86 data, most of which is extremely cryptic.</p><p>Note that specifying this parameter here will
  87 override the <a class="indexterm" name="id2488532"></a> parameter
  88 in the <code class="filename">smb.conf</code> file.</p></dd><dt><span class="term">-l|--logfile=logdirectory</span></dt><dd><p>Base directory name for log/debug files. The extension
  89 <code class="constant">".progname"</code> will be appended (e.g. log.smbclient,
  90 log.smbd, etc...). The log file is never removed by the client.
  91 </p></dd><dt><span class="term">-h|--help</span></dt><dd><p>Print a summary of command line options.
  92 </p></dd><dt><span class="term">-i</span></dt><dd><p>Tells <span><strong class="command">winbindd</strong></span> to not
  93                 become a daemon and detach from the current terminal. This
  94                 option is used by developers when interactive debugging
  95                 of <span><strong class="command">winbindd</strong></span> is required.
  96                 <span><strong class="command">winbindd</strong></span> also logs to standard output,
  97                 as if the <span><strong class="command">-S</strong></span> parameter had been given.
  98                 </p></dd><dt><span class="term">-n</span></dt><dd><p>Disable caching. This means winbindd will
  99                 always have to wait for a response from the domain controller
 100                 before it can respond to a client and this thus makes things
 101                 slower. The results will however be more accurate, since
 102                 results from the cache might not be up-to-date. This
 103                 might also temporarily hang winbindd if the DC doesn't respond.
 104                 </p></dd><dt><span class="term">-Y</span></dt><dd><p>Single daemon mode. This means winbindd will run
 105                 as a single process (the mode of operation in Samba 2.2).  Winbindd's
 106                 default behavior is to launch a child process that is responsible for
 107                 updating expired cache entries.
 108                 </p></dd></dl></div></div><div class="refsect1" lang="en"><a name="id2488863"></a><h2>NAME AND ID RESOLUTION</h2><p>Users and groups on a Windows NT server are assigned
 109         a security id (SID) which is globally unique when the
 110         user or group is created.  To convert the Windows NT user or group
 111         into a unix user or group, a mapping between SIDs and unix user
 112         and group ids is required.  This is one of the jobs that <span><strong class="command">
 113         winbindd</strong></span> performs. </p><p>As winbindd users and groups are resolved from a server, user
 114         and group ids are allocated from a specified range.  This
 115         is done on a first come, first served basis, although all existing
 116         users and groups will be mapped as soon as a client performs a user
 117         or group enumeration command.  The allocated unix ids are stored
 118         in a database file under the Samba lock directory and will be
 119         remembered. </p><p>WARNING: The SID to unix id database is the only location
 120         where the user and group mappings are stored by winbindd.  If this
 121         file is deleted or corrupted, there is no way for winbindd to
 122         determine which user and group ids correspond to Windows NT user
 123         and group rids. </p><p>See the <a class="indexterm" name="id2488903"></a> parameter in
 124         <code class="filename">smb.conf</code> for options for sharing this
 125         database, such as via LDAP.</p></div><div class="refsect1" lang="en"><a name="id2488918"></a><h2>CONFIGURATION</h2><p>Configuration of the <span><strong class="command">winbindd</strong></span> daemon
 126         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
 127         [global] section of smb.conf. </p><div class="itemizedlist"><ul type="disc"><li><p>
 128                 <a class="indexterm" name="id2488950"></a>winbind separator</p></li><li><p>
 129                 <a class="indexterm" name="id2488962"></a>idmap uid</p></li><li><p>
 130                 <a class="indexterm" name="id2488973"></a>idmap gid</p></li><li><p>
 131                 <a class="indexterm" name="id2488985"></a>idmap backend</p></li><li><p>
 132                 <a class="indexterm" name="id2488996"></a>winbind cache time</p></li><li><p>
 133                 <a class="indexterm" name="id2489008"></a>winbind enum users</p></li><li><p>
 134                 <a class="indexterm" name="id2489019"></a>winbind enum groups</p></li><li><p>
 135                 <a class="indexterm" name="id2489031"></a>template homedir</p></li><li><p>
 136                 <a class="indexterm" name="id2489043"></a>template shell</p></li><li><p>
 137                 <a class="indexterm" name="id2489054"></a>winbind use default domain</p></li></ul></div></div><div class="refsect1" lang="en"><a name="id2489065"></a><h2>EXAMPLE SETUP</h2><p>
 138         To setup winbindd for user and group lookups plus
 139         authentication from a domain controller use something like the
 140         following setup. This was tested on an early Red Hat Linux box.
 141         </p><p>In <code class="filename">/etc/nsswitch.conf</code> put the
 142         following:
 143 </p><pre class="programlisting">
 144 passwd: files winbind
 145 group:  files winbind
 146 </pre><p>
 147         </p><p>In <code class="filename">/etc/pam.d/*</code> replace the <em class="parameter"><code>
 148         auth</code></em> lines with something like this:
 149 </p><pre class="programlisting">
 150 auth  required    /lib/security/pam_securetty.so
 151 auth  required    /lib/security/pam_nologin.so
 152 auth  sufficient  /lib/security/pam_winbind.so
 153 auth  required    /lib/security/pam_unix.so \
 154                   use_first_pass shadow nullok
 155 </pre><p>
 156         </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 157         The PAM module pam_unix has recently replaced the module pam_pwdb.
 158         Some Linux systems use the module pam_unix2 in place of pam_unix.
 159         </p></div><p>Note in particular the use of the <em class="parameter"><code>sufficient
 160         </code></em> keyword and the <em class="parameter"><code>use_first_pass</code></em> keyword. </p><p>Now replace the account lines with this: </p><p><span><strong class="command">account    required   /lib/security/pam_winbind.so
 161         </strong></span></p><p>The next step is to join the domain. To do that use the
 162         <span><strong class="command">net</strong></span> program like this:  </p><p><span><strong class="command">net join -S PDC -U Administrator</strong></span></p><p>The username after the <em class="parameter"><code>-U</code></em> can be any
 163         Domain user that has administrator privileges on the machine.
 164         Substitute the name or IP of your PDC for "PDC".</p><p>Next copy <code class="filename">libnss_winbind.so</code> to
 165         <code class="filename">/lib</code> and <code class="filename">pam_winbind.so
 166         </code> to <code class="filename">/lib/security</code>.  A symbolic link needs to be
 167         made from <code class="filename">/lib/libnss_winbind.so</code> to
 168         <code class="filename">/lib/libnss_winbind.so.2</code>.  If you are using an
 169         older version of glibc then the target of the link should be
 170         <code class="filename">/lib/libnss_winbind.so.1</code>.</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
 171         following:
 172 </p><pre class="programlisting">
 173 [global]
 174         winbind separator = +
 175         winbind cache time = 10
 176         template shell = /bin/bash
 177         template homedir = /home/%D/%U
 178         idmap uid = 10000-20000
 179         idmap gid = 10000-20000
 180         workgroup = DOMAIN
 181         security = domain
 182         password server = *
 183 </pre><p>Now start winbindd and you should find that your user and
 184         group database is expanded to include your NT users and groups,
 185         and that you can login to your unix box as a domain user, using
 186         the DOMAIN+user syntax for the username. You may wish to use the
 187         commands <span><strong class="command">getent passwd</strong></span> and <span><strong class="command">getent group
 188         </strong></span> to confirm the correct operation of winbindd.</p></div><div class="refsect1" lang="en"><a name="id2535726"></a><h2>NOTES</h2><p>The following notes are useful when configuring and
 189         running <span><strong class="command">winbindd</strong></span>: </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
 190         for <span><strong class="command">winbindd</strong></span> to work. </p><p>PAM is really easy to misconfigure.  Make sure you know what
 191         you are doing when modifying PAM configuration files.  It is possible
 192         to set up PAM such that you can no longer log into your system. </p><p>If more than one UNIX machine is running <span><strong class="command">winbindd</strong></span>,
 193         then in general the user and groups ids allocated by winbindd will not
 194         be the same.  The user and group ids will only be valid for the local
 195         machine, unless a shared <a class="indexterm" name="id2535777"></a> is configured.</p><p>If the the Windows NT SID to UNIX user and group id mapping
 196         file is damaged or destroyed then the mappings will be lost. </p></div><div class="refsect1" lang="en"><a name="id2535790"></a><h2>SIGNALS</h2><p>The following signals can be used to manipulate the
 197         <span><strong class="command">winbindd</strong></span> 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
 198                 apply any parameter changes to the running
 199                 version of winbindd.  This signal also clears any cached
 200                 user and group information.  The list of other domains trusted
 201                 by winbindd is also reloaded.  </p></dd><dt><span class="term">SIGUSR2</span></dt><dd><p>The SIGUSR2 signal will cause <span><strong class="command">
 202                 winbindd</strong></span> to write status information to the winbind
 203                 log file.</p><p>Log files are stored in the filename specified by the
 204                 log file parameter.</p></dd></dl></div></div><div class="refsect1" lang="en"><a name="id2535856"></a><h2>FILES</h2><div class="variablelist"><dl><dt><span class="term"><code class="filename">/etc/nsswitch.conf(5)</code></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
 205                 the <span><strong class="command">winbindd</strong></span> program.  For security reasons, the
 206                 winbind client will only attempt to connect to the winbindd daemon
 207                 if both the <code class="filename">/tmp/.winbindd</code> directory
 208                 and <code class="filename">/tmp/.winbindd/pipe</code> file are owned by
 209                 root. </p></dd><dt><span class="term">$LOCKDIR/winbindd_privileged/pipe</span></dt><dd><p>The UNIX pipe over which 'privileged' clients
 210                 communicate with the <span><strong class="command">winbindd</strong></span> program.  For security
 211                 reasons, access to some winbindd functions - like those needed by
 212                 the <span><strong class="command">ntlm_auth</strong></span> utility - is restricted.  By default,
 213                 only users in the 'root' group will get this access, however the administrator
 214                 may change the group permissions on $LOCKDIR/winbindd_privileged to allow
 215                 programs like 'squid' to use ntlm_auth.
 216                 Note that the winbind client will only attempt to connect to the winbindd daemon
 217                 if both the <code class="filename">$LOCKDIR/winbindd_privileged</code> directory
 218                 and <code class="filename">$LOCKDIR/winbindd_privileged/pipe</code> file are owned by
 219                 root. </p></dd><dt><span class="term">/lib/libnss_winbind.so.X</span></dt><dd><p>Implementation of name service switch library.
 220                 </p></dd><dt><span class="term">$LOCKDIR/winbindd_idmap.tdb</span></dt><dd><p>Storage for the Windows NT rid to UNIX user/group
 221                 id mapping.  The lock directory is specified when Samba is initially
 222                 compiled using the <em class="parameter"><code>--with-lockdir</code></em> option.
 223                 This directory is by default <code class="filename">/usr/local/samba/var/locks
 224                 </code>. </p></dd><dt><span class="term">$LOCKDIR/winbindd_cache.tdb</span></dt><dd><p>Storage for cached user and group information.
 225                 </p></dd></dl></div></div><div class="refsect1" lang="en"><a name="id2536013"></a><h2>VERSION</h2><p>This man page is correct for version 3.0 of
 226         the Samba suite.</p></div><div class="refsect1" lang="en"><a name="id2536024"></a><h2>SEE ALSO</h2><p><code class="filename">nsswitch.conf(5)</code>, <a href="samba.7.html"><span class="citerefentry"><span class="refentrytitle">samba</span>(7)</span></a>, <a href="wbinfo.1.html"><span class="citerefentry"><span class="refentrytitle">wbinfo</span>(1)</span></a>, <a href="ntlm_auth.8.html"><span class="citerefentry"><span class="refentrytitle">ntlm_auth</span>(8)</span></a>, <a href="smb.conf.5.html"><span class="citerefentry"><span class="refentrytitle">smb.conf</span>(5)</span></a>, <a href="pam_winbind.8.html"><span class="citerefentry"><span class="refentrytitle">pam_winbind</span>(8)</span></a></p></div><div class="refsect1" lang="en"><a name="id2536082"></a><h2>AUTHOR</h2><p>The original Samba software and related utilities
 227         were created by Andrew Tridgell. Samba is now developed
 228         by the Samba Team as an Open Source project similar
 229         to the way the Linux kernel is developed.</p><p><span><strong class="command">wbinfo</strong></span> and <span><strong class="command">winbindd</strong></span> were
 230         written by Tim Potter.</p><p>The conversion to DocBook for Samba 2.2 was done
 231         by Gerald Carter. The conversion to DocBook XML 4.2 for
 232         Samba 3.0 was done by Alexander Bokovoy.</p></div></div></body></html>