docs/docbook/manpages/winbindd.8.xml

   1 <?xml version="1.0" encoding="iso8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4
   5 <!ENTITY % globalentities SYSTEM './../global.ent'> %globalentities;
   6 ]>
   7 <refentry id="winbindd.8">
   8
   9 <refmeta>
  10         <refentrytitle>winbindd</refentrytitle>
  11         <manvolnum>8</manvolnum>
  12 </refmeta>
  13
  14
  15 <refnamediv>
  16         <refname>winbindd</refname>
  17         <refpurpose>Name Service Switch daemon for resolving names
  18         from NT servers</refpurpose>
  19 </refnamediv>
  20
  21 <refsynopsisdiv>
  22         <cmdsynopsis>
  23                 <command>winbindd</command>
  24                 <arg choice="opt">-F</arg>
  25                 <arg choice="opt">-S</arg>
  26                 <arg choice="opt">-i</arg>
  27                 <arg choice="opt">-B</arg>
  28                 <arg choice="opt">-d &lt;debug level&gt;</arg>
  29                 <arg choice="opt">-s &lt;smb config file&gt;</arg>
  30                 <arg choice="opt">-n</arg>
  31         </cmdsynopsis>
  32 </refsynopsisdiv>
  33
  34 <refsect1>
  35         <title>DESCRIPTION</title>
  36
  37         <para>This program is part of the <citerefentry><refentrytitle>Samba</refentrytitle>
  38         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  39
  40         <para><command>winbindd</command> is a daemon that provides
  41         a service for the Name Service Switch capability that is present
  42         in most modern C libraries.  The Name Service Switch allows user
  43         and system information to be obtained from different databases
  44         services such as NIS or DNS.  The exact behaviour can be configured
  45         throught the <filename>/etc/nsswitch.conf</filename> file.
  46         Users and groups are allocated as they are resolved to a range
  47         of user and group ids specified by the administrator of the
  48         Samba system.</para>
  49
  50         <para>The service provided by <command>winbindd</command> is called `winbind' and
  51         can be used to resolve user and group information from a
  52         Windows NT server. The service can also provide authentication
  53         services via an associated PAM module. </para>
  54
  55         <para>
  56         The <filename>pam_winbind</filename> module in the 2.2.2 release only
  57         supports the <parameter>auth</parameter> and <parameter>account</parameter>
  58         module-types.  The latter simply
  59         performs a getpwnam() to verify that the system can obtain a uid for the
  60         user.  If the <filename>libnss_winbind</filename> library has been correctly
  61         installed, this should always succeed.
  62         </para>
  63
  64         <para>The following nsswitch databases are implemented by
  65         the winbindd service: </para>
  66
  67         <variablelist>
  68                 <varlistentry>
  69                 <term>hosts</term>
  70                 <listitem><para>User information traditionally stored in
  71                 the <filename>hosts(5)</filename> file and used by
  72                 <command>gethostbyname(3)</command> functions. Names are
  73                 resolved through the WINS server or by broadcast.
  74                 </para></listitem>
  75                 </varlistentry>
  76
  77                 <varlistentry>
  78                 <term>passwd</term>
  79                 <listitem><para>User information traditionally stored in
  80                 the <filename>passwd(5)</filename> file and used by
  81                 <command>getpwent(3)</command> functions. </para></listitem>
  82                 </varlistentry>
  83
  84                 <varlistentry>
  85                 <term>group</term>
  86                 <listitem><para>Group information traditionally stored in
  87                 the <filename>group(5)</filename> file and used by
  88                 <command>getgrent(3)</command> functions. </para></listitem>
  89                 </varlistentry>
  90         </variablelist>
  91
  92         <para>For example, the following simple configuration in the
  93         <filename>/etc/nsswitch.conf</filename> file can be used to initially
  94         resolve user and group information from <filename>/etc/passwd
  95         </filename> and <filename>/etc/group</filename> and then from the
  96         Windows NT server.
  97 <programlisting>
  98 passwd:         files winbind
  99 group:          files winbind
 100 </programlisting></para>
 101
 102         <para>The following simple configuration in the
 103         <filename>/etc/nsswitch.conf</filename> file can be used to initially
 104         resolve hostnames from <filename>/etc/hosts</filename> and then from the
 105         WINS server.</para>
 106
 107 </refsect1>
 108
 109
 110 <refsect1>
 111         <title>OPTIONS</title>
 112
 113         <variablelist>
 114                 <varlistentry>
 115                 <term>-F</term>
 116                 <listitem><para>If specified, this parameter causes
 117                 the main <command>winbindd</command> process to not daemonize,
 118                 i.e. double-fork and disassociate with the terminal.
 119                 Child processes are still created as normal to service
 120                 each connection request, but the main process does not
 121                 exit. This operation mode is suitable for running
 122                 <command>winbindd</command> under process supervisors such
 123                 as <command>supervise</command> and <command>svscan</command>
 124                 from Daniel J. Bernstein's <command>daemontools</command>
 125                 package, or the AIX process monitor.
 126                 </para></listitem>
 127                 </varlistentry>
 128
 129                 <varlistentry>
 130                 <term>-S</term>
 131                 <listitem><para>If specified, this parameter causes
 132                 <command>winbindd</command> to log to standard output rather
 133                 than a file.</para></listitem>
 134                 </varlistentry>
 135
 136                 &popt.common.samba;
 137                 &stdarg.help;
 138
 139                 <varlistentry>
 140                 <term>-i</term>
 141                 <listitem><para>Tells <command>winbindd</command> to not
 142                 become a daemon and detach from the current terminal. This
 143                 option is used by developers when interactive debugging
 144                 of <command>winbindd</command> is required.
 145                 <command>winbindd</command> also logs to standard output,
 146                 as if the <command>-S</command> parameter had been given.
 147                 </para></listitem>
 148                 </varlistentry>
 149
 150                 <varlistentry>
 151                 <term>-n</term>
 152                 <listitem><para>Disable caching. This means winbindd will
 153                 always have to wait for a response from the domain controller
 154                 before it can respond to a client and this thus makes things
 155                 slower. The results will however be more accurate, since
 156                 results from the cache might not be up-to-date. This
 157                 might also temporarily hang winbindd if the DC doesn't respond.
 158                 </para></listitem>
 159                 </varlistentry>
 160
 161                 <varlistentry>
 162                 <term>-B</term>
 163                 <listitem><para>Dual daemon mode. This means winbindd will run
 164                 as 2 threads. The first will answer all requests from the cache,
 165                 thus making responses to clients faster. The other will
 166                 update the cache for the query that the first has just responded.
 167                 Advantage of this is that responses stay accurate and are faster.
 168                 </para></listitem>
 169                 </varlistentry>
 170
 171         </variablelist>
 172 </refsect1>
 173
 174
 175 <refsect1>
 176         <title>NAME AND ID RESOLUTION</title>
 177
 178         <para>Users and groups on a Windows NT server are assigned
 179         a relative id (rid) which is unique for the domain when the
 180         user or group is created.  To convert the Windows NT user or group
 181         into a unix user or group, a mapping between rids and unix user
 182         and group ids is required.  This is one of the jobs that <command>
 183         winbindd</command> performs. </para>
 184
 185         <para>As winbindd users and groups are resolved from a server, user
 186         and group ids are allocated from a specified range.  This
 187         is done on a first come, first served basis, although all existing
 188         users and groups will be mapped as soon as a client performs a user
 189         or group enumeration command.  The allocated unix ids are stored
 190         in a database file under the Samba lock directory and will be
 191         remembered. </para>
 192
 193         <para>WARNING: The rid to unix id database is the only location
 194         where the user and group mappings are stored by winbindd.  If this
 195         file is deleted or corrupted, there is no way for winbindd to
 196         determine which user and group ids correspond to Windows NT user
 197         and group rids. </para>
 198 </refsect1>
 199
 200
 201 <refsect1>
 202         <title>CONFIGURATION</title>
 203
 204         <para>Configuration of the <command>winbindd</command> daemon
 205         is done through configuration parameters in the <citerefentry>
 206         <refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum>
 207         </citerefentry> file.  All parameters should be specified in the
 208         [global] section of smb.conf. </para>
 209
 210         <itemizedlist>
 211                 <listitem><para><ulink url="smb.conf.5.html#WINBINDSEPARATOR">
 212                 <parameter>winbind separator</parameter></ulink></para></listitem>
 213                 <listitem><para><ulink url="smb.conf.5.html#WINBINDUID">
 214                 <parameter>winbind uid</parameter></ulink></para></listitem>
 215                 <listitem><para><ulink url="smb.conf.5.html#WINBINDGID">
 216                 <parameter>winbind gid</parameter></ulink></para></listitem>
 217                 <listitem><para><ulink url="smb.conf.5.html#WINBINDCACHETIME">
 218                 <parameter>winbind cache time</parameter></ulink></para></listitem>
 219                 <listitem><para><ulink url="smb.conf.5.html#WINBINDENUMUSERS">
 220                 <parameter>winbind enum users</parameter></ulink></para></listitem>
 221                 <listitem><para><ulink url="smb.conf.5.html#WINBINDENUMGROUPS">
 222                 <parameter>winbind enum groups</parameter></ulink></para></listitem>
 223                 <listitem><para><ulink url="smb.conf.5.html#TEMPLATEHOMEDIR">
 224                 <parameter>template homedir</parameter></ulink></para></listitem>
 225                 <listitem><para><ulink url="smb.conf.5.html#TEMPLATESHELL">
 226                 <parameter>template shell</parameter></ulink></para></listitem>
 227                 <listitem><para><ulink url="smb.conf.5.html#WINBINDUSEDEFAULTDOMAIN">
 228                 <parameter>winbind use default domain</parameter></ulink></para></listitem>
 229         </itemizedlist>
 230 </refsect1>
 231
 232
 233 <refsect1>
 234         <title>EXAMPLE SETUP</title>
 235
 236         <para>To setup winbindd for user and group lookups plus
 237         authentication from a domain controller use something like the
 238         following setup. This was tested on a RedHat 6.2 Linux box. </para>
 239
 240         <para>In <filename>/etc/nsswitch.conf</filename> put the
 241         following:
 242 <programlisting>
 243 passwd:     files winbind
 244 group:      files winbind
 245 </programlisting></para>
 246
 247         <para>In <filename>/etc/pam.d/*</filename> replace the <parameter>
 248         auth</parameter> lines with something like this:
 249 <programlisting>
 250 auth       required     /lib/security/pam_securetty.so
 251 auth       required     /lib/security/pam_nologin.so
 252 auth       sufficient   /lib/security/pam_winbind.so
 253 auth       required     /lib/security/pam_pwdb.so use_first_pass shadow nullok
 254 </programlisting></para>
 255
 256
 257         <para>Note in particular the use of the <parameter>sufficient
 258         </parameter> keyword and the <parameter>use_first_pass</parameter> keyword. </para>
 259
 260         <para>Now replace the account lines with this: </para>
 261
 262         <para><command>account    required      /lib/security/pam_winbind.so
 263         </command></para>
 264
 265         <para>The next step is to join the domain. To do that use the
 266         <command>net</command> program like this:  </para>
 267
 268         <para><command>net join -S PDC -U Administrator</command></para>
 269
 270         <para>The username after the <parameter>-U</parameter> can be any
 271         Domain user that has administrator privileges on the machine.
 272         Substitute the name or IP of your PDC for "PDC".</para>
 273
 274         <para>Next copy <filename>libnss_winbind.so</filename> to
 275         <filename>/lib</filename> and <filename>pam_winbind.so
 276         </filename> to <filename>/lib/security</filename>.  A symbolic link needs to be
 277         made from <filename>/lib/libnss_winbind.so</filename> to
 278         <filename>/lib/libnss_winbind.so.2</filename>.  If you are using an
 279         older version of glibc then the target of the link should be
 280         <filename>/lib/libnss_winbind.so.1</filename>.</para>
 281
 282         <para>Finally, setup a <citerefentry><refentrytitle>smb.conf</refentrytitle>
 283         <manvolnum>5</manvolnum></citerefentry> containing directives like the
 284         following:
 285 <programlisting>
 286 [global]
 287         winbind separator = +
 288         winbind cache time = 10
 289         template shell = /bin/bash
 290         template homedir = /home/%D/%U
 291         winbind uid = 10000-20000
 292         winbind gid = 10000-20000
 293         workgroup = DOMAIN
 294         security = domain
 295         password server = *
 296 </programlisting></para>
 297
 298
 299         <para>Now start winbindd and you should find that your user and
 300         group database is expanded to include your NT users and groups,
 301         and that you can login to your unix box as a domain user, using
 302         the DOMAIN+user syntax for the username. You may wish to use the
 303         commands <command>getent passwd</command> and <command>getent group
 304         </command> to confirm the correct operation of winbindd.</para>
 305 </refsect1>
 306
 307
 308 <refsect1>
 309         <title>NOTES</title>
 310
 311         <para>The following notes are useful when configuring and
 312         running <command>winbindd</command>: </para>
 313
 314         <para><citerefentry><refentrytitle>nmbd</refentrytitle>
 315         <manvolnum>8</manvolnum></citerefentry> must be running on the local machine
 316         for <command>winbindd</command> to work. <command>winbindd</command> queries
 317         the list of trusted domains for the Windows NT server
 318         on startup and when a SIGHUP is received.  Thus, for a running <command>
 319         winbindd</command> to become aware of new trust relationships between
 320         servers, it must be sent a SIGHUP signal. </para>
 321
 322         <para>PAM is really easy to misconfigure.  Make sure you know what
 323         you are doing when modifying PAM configuration files.  It is possible
 324         to set up PAM such that you can no longer log into your system. </para>
 325
 326         <para>If more than one UNIX machine is running <command>winbindd</command>,
 327         then in general the user and groups ids allocated by winbindd will not
 328         be the same.  The user and group ids will only be valid for the local
 329         machine.</para>
 330
 331         <para>If the the Windows NT RID to UNIX user and group id mapping
 332         file is damaged or destroyed then the mappings will be lost. </para>
 333 </refsect1>
 334
 335
 336 <refsect1>
 337         <title>SIGNALS</title>
 338
 339         <para>The following signals can be used to manipulate the
 340         <command>winbindd</command> daemon. </para>
 341
 342         <variablelist>
 343                 <varlistentry>
 344                 <term>SIGHUP</term>
 345                 <listitem><para>Reload the <citerefentry><refentrytitle>smb.conf</refentrytitle>
 346                 <manvolnum>5</manvolnum></citerefentry> file and
 347                 apply any parameter changes to the running
 348                 version of winbindd.  This signal also clears any cached
 349                 user and group information.  The list of other domains trusted
 350                 by winbindd is also reloaded.  </para></listitem>
 351                 </varlistentry>
 352
 353                 <varlistentry>
 354                 <term>SIGUSR1</term>
 355                 <listitem><para>The SIGUSR1 signal will cause <command>
 356                 winbindd</command> to write status information to the winbind
 357                 log file including information about the number of user and
 358                 group ids allocated by <command>winbindd</command>.</para>
 359
 360                 <para>Log files are stored in the filename specified by the
 361                 log file parameter.</para></listitem>
 362                 </varlistentry>
 363         </variablelist>
 364 </refsect1>
 365
 366 <refsect1>
 367         <title>FILES</title>
 368
 369         <variablelist>
 370                 <varlistentry>
 371                 <term><filename>/etc/nsswitch.conf(5)</filename></term>
 372                 <listitem><para>Name service switch configuration file.</para>
 373                 </listitem>
 374                 </varlistentry>
 375
 376                 <varlistentry>
 377                 <term>/tmp/.winbindd/pipe</term>
 378                 <listitem><para>The UNIX pipe over which clients communicate with
 379                 the <command>winbindd</command> program.  For security reasons, the
 380                 winbind client will only attempt to connect to the winbindd daemon
 381                 if both the <filename>/tmp/.winbindd</filename> directory
 382                 and <filename>/tmp/.winbindd/pipe</filename> file are owned by
 383                 root. </para></listitem>
 384                 </varlistentry>
 385
 386                 <varlistentry>
 387                 <term>$LOCKDIR/winbindd_privilaged/pipe</term>
 388                 <listitem><para>The UNIX pipe over which 'privilaged' clients
 389                 communicate with the <command>winbindd</command> program.  For security
 390                 reasons, access to some winbindd functions - like those needed by
 391                 the <command>ntlm_auth</command> utility - is restricted.  By default,
 392                 only users in the 'root' group will get this access, however the administrator
 393                 may change the group permissions on $LOCKDIR/winbindd_privilaged to allow
 394                 programs like 'squid' to use ntlm_auth.
 395                 Note that the winbind client will only attempt to connect to the winbindd daemon
 396                 if both the <filename>$LOCKDIR/winbindd_privilaged</filename> directory
 397                 and <filename>$LOCKDIR/winbindd_privilaged/pipe</filename> file are owned by
 398                 root. </para></listitem>
 399                 </varlistentry>
 400
 401                 <varlistentry>
 402                 <term>/lib/libnss_winbind.so.X</term>
 403                 <listitem><para>Implementation of name service switch library.
 404                 </para></listitem>
 405                 </varlistentry>
 406
 407                 <varlistentry>
 408                 <term>$LOCKDIR/winbindd_idmap.tdb</term>
 409                 <listitem><para>Storage for the Windows NT rid to UNIX user/group
 410                 id mapping.  The lock directory is specified when Samba is initially
 411                 compiled using the <parameter>--with-lockdir</parameter> option.
 412                 This directory is by default <filename>/usr/local/samba/var/locks
 413                 </filename>. </para></listitem>
 414                 </varlistentry>
 415
 416                 <varlistentry>
 417                 <term>$LOCKDIR/winbindd_cache.tdb</term>
 418                 <listitem><para>Storage for cached user and group information.
 419                 </para></listitem>
 420                 </varlistentry>
 421         </variablelist>
 422 </refsect1>
 423
 424
 425 <refsect1>
 426         <title>VERSION</title>
 427
 428         <para>This man page is correct for version 3.0 of
 429         the Samba suite.</para>
 430 </refsect1>
 431
 432 <refsect1>
 433         <title>SEE ALSO</title>
 434
 435         <para><filename>nsswitch.conf(5)</filename>, <citerefentry>
 436         <refentrytitle>Samba</refentrytitle>
 437         <manvolnum>7</manvolnum></citerefentry>, <citerefentry>
 438         <refentrytitle>wbinfo</refentrytitle>
 439         <manvolnum>8</manvolnum></citerefentry>, <citerefentry>
 440         <refentrytitle>smb.conf</refentrytitle>
 441         <manvolnum>5</manvolnum></citerefentry></para>
 442 </refsect1>
 443
 444 <refsect1>
 445         <title>AUTHOR</title>
 446
 447         <para>The original Samba software and related utilities
 448         were created by Andrew Tridgell. Samba is now developed
 449         by the Samba Team as an Open Source project similar
 450         to the way the Linux kernel is developed.</para>
 451
 452         <para><command>wbinfo</command> and <command>winbindd</command> were
 453         written by Tim Potter.</para>
 454
 455         <para>The conversion to DocBook for Samba 2.2 was done
 456         by Gerald Carter. The conversion to DocBook XML 4.2 for
 457         Samba 3.0 was done by Alexander Bokovoy.</para>
 458 </refsect1>
 459
 460 </refentry>