docs/manpages/winbindd.8.xml

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