docs/docbook/manpages/winbindd.8.sgml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <refentry id="winbindd">
   3
   4 <refmeta>
   5         <refentrytitle>winbindd</refentrytitle>
   6         <manvolnum>8</manvolnum>
   7 </refmeta>
   8
   9
  10 <refnamediv>
  11         <refname>winbindd</refname>
  12         <refpurpose>Name Service Switch daemon for resolving names
  13         from NT servers</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17         <cmdsynopsis>
  18                 <command>winbindd</command>
  19                 <arg choice="opt">-i</arg>
  20                 <arg choice="opt">-d &lt;debug level&gt;</arg>
  21                 <arg choice="opt">-s &lt;smb config file&gt;</arg>
  22         </cmdsynopsis>
  23 </refsynopsisdiv>
  24
  25 <refsect1>
  26         <title>DESCRIPTION</title>
  27
  28         <para>This program is part of the <ulink url="samba.7.html">
  29         Samba</ulink> suite.</para>
  30
  31         <para><command>winbindd</command> is a daemon that provides
  32         a service for the Name Service Switch capability that is present
  33         in most modern C libraries.  The Name Service Switch allows user
  34         and system information to be obtained from different databases
  35         services such as NIS or DNS.  The exact behaviour can be configured
  36         throught the <filename>/etc/nsswitch.conf</filename> file.
  37         Users and groups are allocated as they are resolved to a range
  38         of user and group ids specified by the administrator of the
  39         Samba system.</para>
  40
  41         <para>The service provided by <command>winbindd</command> is called `winbind' and
  42         can be used to resolve user and group information from a
  43         Windows NT server. The service can also provide authentication
  44         services via an associated PAM module. </para>
  45
  46         <para>
  47         The <filename>pam_winbind</filename> module in the 2.2.2 release only
  48         supports the <parameter>auth</parameter> and <parameter>account</parameter>
  49         module-types.  The latter is simply
  50         performs a getpwnam() to verify that the system can obtain a uid for the
  51         user.  If the <filename>libnss_winbind</filename> library has been correctly
  52         installed, this should always suceed.
  53         </para>
  54
  55         <para>The following nsswitch databases are implemented by
  56         the winbindd service: </para>
  57
  58         <variablelist>
  59                 <varlistentry>
  60                 <term>hosts</term>
  61                 <listitem><para>User information traditionally stored in
  62                 the <filename>hosts(5)</filename> file and used by
  63                 <command>gethostbyname(3)</command> functions. Names are
  64                 resolved through the WINS server or by broadcast.
  65                 </para></listitem>
  66                 </varlistentry>
  67
  68                 <varlistentry>
  69                 <term>passwd</term>
  70                 <listitem><para>User information traditionally stored in
  71                 the <filename>passwd(5)</filename> file and used by
  72                 <command>getpwent(3)</command> functions. </para></listitem>
  73                 </varlistentry>
  74
  75                 <varlistentry>
  76                 <term>group</term>
  77                 <listitem><para>Group information traditionally stored in
  78                 the <filename>group(5)</filename> file and used by
  79                 <command>getgrent(3)</command> functions. </para></listitem>
  80                 </varlistentry>
  81         </variablelist>
  82
  83         <para>For example, the following simple configuration in the
  84         <filename>/etc/nsswitch.conf</filename> file can be used to initially
  85         resolve user and group information from <filename>/etc/passwd
  86         </filename> and <filename>/etc/group</filename> and then from the
  87         Windows NT server. </para>
  88
  89         <para><programlisting>
  90 passwd:         files winbind
  91 group:          files winbind
  92         </programlisting></para>
  93
  94         <para>The following simple configuration in the
  95         <filename>/etc/nsswitch.conf</filename> file can be used to initially
  96         resolve hostnames from <filename>/etc/hosts</filename> and then from the
  97         WINS server.</para>
  98
  99 </refsect1>
 100
 101
 102 <refsect1>
 103         <title>OPTIONS</title>
 104
 105         <variablelist>
 106                 <varlistentry>
 107                 <term>-d debuglevel</term>
 108                 <listitem><para>Sets the debuglevel to an integer between
 109                 0 and 100. 0 is for no debugging and 100 is for reams and
 110                 reams. To submit a bug report to the Samba Team, use debug
 111                 level 100 (see BUGS.txt).   </para></listitem>
 112                 </varlistentry>
 113
 114                 <varlistentry>
 115                 <term>-i</term>
 116                 <listitem><para>Tells <command>winbindd</command> to not
 117                 become a daemon and detach from the current terminal. This
 118                 option is used by developers when interactive debugging
 119                 of <command>winbindd</command> is required. </para></listitem>
 120                 </varlistentry>
 121         </variablelist>
 122 </refsect1>
 123
 124
 125 <refsect1>
 126         <title>NAME AND ID RESOLUTION</title>
 127
 128         <para>Users and groups on a Windows NT server are assigned
 129         a relative id (rid) which is unique for the domain when the
 130         user or group is created.  To convert the Windows NT user or group
 131         into a unix user or group, a mapping between rids and unix user
 132         and group ids is required.  This is one of the jobs that <command>
 133         winbindd</command> performs. </para>
 134
 135         <para>As winbindd users and groups are resolved from a server, user
 136         and group ids are allocated from a specified range.  This
 137         is done on a first come, first served basis, although all existing
 138         users and groups will be mapped as soon as a client performs a user
 139         or group enumeration command.  The allocated unix ids are stored
 140         in a database file under the Samba lock directory and will be
 141         remembered. </para>
 142
 143         <para>WARNING: The rid to unix id database is the only location
 144         where the user and group mappings are stored by winbindd.  If this
 145         file is deleted or corrupted, there is no way for winbindd to
 146         determine which user and group ids correspond to Windows NT user
 147         and group rids. </para>
 148 </refsect1>
 149
 150
 151 <refsect1>
 152         <title>CONFIGURATION</title>
 153
 154         <para>Configuration of the <command>winbindd</command> daemon
 155         is done through configuration parameters in the <filename>smb.conf(5)
 156         </filename> file.  All parameters should be specified in the
 157         [global] section of smb.conf. </para>
 158
 159         <variablelist>
 160                 <varlistentry>
 161                 <term>winbind separator</term>
 162                 <listitem><para>The winbind separator option allows you
 163                 to specify how NT domain names and user names are combined
 164                 into unix user names when presented to users. By default,
 165                 <command>winbindd</command> will use the traditional '\'
 166                 separator so that the unix user names look like
 167                 DOMAIN\username. In some cases this separator character may
 168                 cause problems as the '\' character has special meaning in
 169                 unix shells.  In that case you can use the winbind separator
 170                 option to specify an alternative separator character. Good
 171                 alternatives may be '/' (although that conflicts
 172                 with the unix directory separator) or a '+ 'character.
 173                 The '+' character appears to be the best choice for 100%
 174                 compatibility with existing unix utilities, but may be an
 175                 aesthetically bad choice depending on your taste. </para>
 176
 177                 <para>Default: <command>winbind separator = \ </command>
 178                 </para>
 179                 <para>Example: <command>winbind separator = + </command></para>
 180                 </listitem>
 181                 </varlistentry>
 182
 183                 <varlistentry>
 184                 <term>winbind uid</term>
 185                 <listitem><para>The winbind uid parameter specifies the
 186                 range of user ids that are allocated by the winbindd daemon.
 187                 This range of ids should have no existing local or NIS users
 188                 within it as strange conflicts can occur otherwise. </para>
 189
 190                 <para>Default: <command>winbind uid = &lt;empty string&gt;
 191                 </command></para>
 192                 <para>Example: <command>winbind uid = 10000-20000</command></para>
 193                 </listitem>
 194                 </varlistentry>
 195
 196
 197                 <varlistentry>
 198                 <term>winbind gid</term>
 199                 <listitem><para>The winbind gid parameter specifies the
 200                 range of group ids that are allocated by the winbindd daemon.
 201                 This range of group ids should have no existing local or NIS
 202                 groups within it as strange conflicts can occur otherwise.</para>
 203
 204                 <para>Default: <command>winbind gid = &lt;empty string&gt;
 205                 </command></para>
 206                 <para>Example: <command>winbind gid = 10000-20000
 207                 </command> </para></listitem>
 208                 </varlistentry>
 209
 210
 211                 <varlistentry>
 212                 <term>winbind cache time</term>
 213                 <listitem><para>This parameter specifies the number of
 214                 seconds the winbindd daemon will cache user and group information
 215                 before querying a Windows NT server again. When a item in the
 216                 cache is older than this time winbindd will ask the domain
 217                 controller for the sequence number of the server's account database.
 218                 If the sequence number has not changed then the cached item is
 219                 marked as valid for a further <parameter>winbind cache time
 220                 </parameter> seconds.  Otherwise the item is fetched from the
 221                 server. This means that as long as the account database is not
 222                 actively changing winbindd will only have to send one sequence
 223                 number query packet every <parameter>winbind cache time
 224                 </parameter> seconds. </para>
 225
 226                 <para>Default: <command>winbind cache time = 15</command>
 227                 </para></listitem>
 228                 </varlistentry>
 229
 230                 <varlistentry>
 231                 <term>winbind enum users</term>
 232                 <listitem><para>On large installations it may be necessary
 233                 to suppress the enumeration of users through the <command>
 234                 setpwent()</command>, <command>getpwent()</command> and
 235                 <command>endpwent()</command> group of system calls.  If
 236                 the <parameter>winbind enum users</parameter> parameter is false,
 237                 calls to the <command>getpwent</command> system call will not
 238                 return any data. </para>
 239
 240                 <para><emphasis>Warning:</emphasis> Turning off user enumeration
 241                 may cause some programs to behave oddly.  For example, the <command>finger</command>
 242                 program relies on having access to the full user list when
 243                 searching  for matching usernames. </para>
 244
 245                 <para>Default: <command>winbind enum users = yes </command></para>
 246                 </listitem>
 247                 </varlistentry>
 248
 249                 <varlistentry>
 250                 <term>winbind enum groups</term>
 251                 <listitem><para>On large installations it may be necessary
 252                 to suppress the enumeration of groups through the <command>
 253                 setgrent()</command>, <command>getgrent()</command> and
 254                 <command>endgrent()</command> group of system calls.  If
 255                 the <parameter>winbind enum groups</parameter> parameter is
 256                 false, calls to the <command>getgrent()</command> system
 257                 call will not return any data. </para>
 258
 259                 <para><emphasis>Warning:</emphasis> Turning off group
 260                 enumeration may cause some programs to behave oddly.
 261                 </para>
 262
 263                 <para>Default: <command>winbind enum groups = no </command>
 264                 </para></listitem>
 265                 </varlistentry>
 266
 267
 268
 269                 <varlistentry>
 270                 <term>template homedir</term>
 271                 <listitem><para>When filling out the user information
 272                 for a Windows NT user, the <command>winbindd</command> daemon
 273                 uses this parameter to fill in the home directory for that user.
 274                 If the string <parameter>%D</parameter> is present it is
 275                 substituted with the user's Windows NT domain name.  If the
 276                 string <parameter>%U</parameter> is present it is substituted
 277                 with the user's Windows NT user name. </para>
 278
 279                 <para>Default: <command>template homedir = /home/%D/%U </command>
 280                 </para></listitem>
 281                 </varlistentry>
 282
 283
 284                 <varlistentry>
 285                 <term>template shell</term>
 286                 <listitem><para>When filling out the user information for
 287                 a Windows NT user, the <command>winbindd</command> daemon
 288                 uses this parameter to fill in the shell for that user.
 289                 </para>
 290
 291                 <para>Default: <command>template shell = /bin/false </command>
 292                 </para></listitem>
 293                 </varlistentry>
 294
 295                 <varlistentry>
 296                 <term>winbind use default domain</term>
 297                 <listitem><para>This parameter specifies whether the <command>winbindd</command>
 298                 daemon should operate on users without domain component in their username.
 299                 Users without a domain component are treated as is part of the winbindd server's
 300                 own domain.  While this does not benifit Windows users, it makes SSH, FTP and e-mail
 301                 function in a way much closer to the way they would in a native unix system.</para>
 302
 303                 <para>Default: <command>winbind use default domain = &lt;falseg&gt;
 304                 </command></para>
 305                 <para>Example: <command>winbind use default domain = true</command></para>
 306                 </listitem>
 307                 </varlistentry>
 308         </variablelist>
 309 </refsect1>
 310
 311
 312 <refsect1>
 313         <title>EXAMPLE SETUP</title>
 314
 315         <para>To setup winbindd for user and group lookups plus
 316         authentication from a domain controller use something like the
 317         following setup. This was tested on a RedHat 6.2 Linux box. </para>
 318
 319         <para>In <filename>/etc/nsswitch.conf</filename> put the
 320         following:</para>
 321
 322         <para><programlisting>
 323 passwd:     files winbind
 324 group:      files winbind
 325         </programlisting></para>
 326
 327         <para>In <filename>/etc/pam.d/*</filename> replace the
 328         <parameter>auth</parameter> lines with something like this: </para>
 329
 330
 331         <para><programlisting>
 332 auth       required     /lib/security/pam_securetty.so
 333 auth       required     /lib/security/pam_nologin.so
 334 auth       sufficient   /lib/security/pam_winbind.so
 335 auth       required     /lib/security/pam_pwdb.so use_first_pass shadow nullok
 336         </programlisting></para>
 337
 338
 339         <para>Note in particular the use of the <parameter>sufficient</parameter>
 340         keyword and the <parameter>use_first_pass</parameter> keyword. </para>
 341
 342         <para>Now replace the account lines with this: </para>
 343
 344         <para><command>account    required      /lib/security/pam_winbind.so
 345         </command></para>
 346
 347         <para>The next step is to join the domain. To do that use the
 348         <command>smbpasswd</command> program like this:  </para>
 349
 350         <para><command>smbpasswd -j DOMAIN -r PDC -U
 351         Administrator</command></para>
 352
 353         <para>The username after the <parameter>-U</parameter> can be any
 354         Domain user that has administrator privileges on the machine.
 355         Substitute your domain name for "DOMAIN" and the name of your PDC
 356         for "PDC".</para>
 357
 358         <para>Next copy <filename>libnss_winbind.so</filename> to
 359         <filename>/lib</filename> and <filename>pam_winbind.so</filename>
 360         to <filename>/lib/security</filename>.  A symbolic link needs to be
 361         made from <filename>/lib/libnss_winbind.so</filename> to
 362         <filename>/lib/libnss_winbind.so.2</filename>.  If you are using an
 363         older version of glibc then the target of the link should be
 364         <filename>/lib/libnss_winbind.so.1</filename>.</para>
 365
 366         <para>Finally, setup a <filename>smb.conf</filename> containing directives like the
 367         following:  </para>
 368
 369         <para><programlisting>
 370 [global]
 371         winbind separator = +
 372         winbind cache time = 10
 373         template shell = /bin/bash
 374         template homedir = /home/%D/%U
 375         winbind uid = 10000-20000
 376         winbind gid = 10000-20000
 377         workgroup = DOMAIN
 378         security = domain
 379         password server = *
 380         </programlisting></para>
 381
 382
 383         <para>Now start winbindd and you should find that your user and
 384         group database is expanded to include your NT users and groups,
 385         and that you can login to your unix box as a domain user, using
 386         the DOMAIN+user syntax for the username. You may wish to use the
 387         commands <command>getent passwd</command> and <command>getent group
 388         </command> to confirm the correct operation of winbindd.</para>
 389 </refsect1>
 390
 391
 392 <refsect1>
 393         <title>NOTES</title>
 394
 395         <para>The following notes are useful when configuring and
 396         running <command>winbindd</command>: </para>
 397
 398         <para><command>nmbd</command> must be running on the local machine
 399         for <command>winbindd</command> to work. <command>winbindd</command>
 400         queries the list of trusted domains for the Windows NT server
 401         on startup and when a SIGHUP is received.  Thus, for a running <command>
 402         winbindd</command> to become aware of new trust relationships between
 403         servers, it must be sent a SIGHUP signal. </para>
 404
 405         <para>Client processes resolving names through the <command>winbindd</command>
 406         nsswitch module read an environment variable named <envar>
 407         $WINBINDD_DOMAIN</envar>.  If this variable contains a comma separated
 408         list of Windows NT domain names, then winbindd will only resolve users
 409         and groups within those Windows NT domains. </para>
 410
 411         <para>PAM is really easy to misconfigure.  Make sure you know what
 412         you are doing when modifying PAM configuration files.  It is possible
 413         to set up PAM such that you can no longer log into your system. </para>
 414
 415         <para>If more than one UNIX machine is running <command>winbindd</command>,
 416         then in general the user and groups ids allocated by winbindd will not
 417         be the same.  The user and group ids will only be valid for the local
 418         machine.</para>
 419
 420         <para>If the the Windows NT RID to UNIX user and group id mapping
 421         file is damaged or destroyed then the mappings will be lost. </para>
 422 </refsect1>
 423
 424
 425 <refsect1>
 426         <title>SIGNALS</title>
 427
 428         <para>The following signals can be used to manipulate the
 429         <command>winbindd</command> daemon. </para>
 430
 431         <variablelist>
 432                 <varlistentry>
 433                 <term>SIGHUP</term>
 434                 <listitem><para>Reload the <filename>smb.conf(5)</filename>
 435                 file and apply any parameter changes to the running
 436                 version of winbindd.  This signal also clears any cached
 437                 user and group information.  The list of other domains trusted
 438                 by winbindd is also reloaded.  </para></listitem>
 439                 </varlistentry>
 440
 441                 <varlistentry>
 442                 <term>SIGUSR1</term>
 443                 <listitem><para>The SIGUSR1 signal will cause <command>
 444                 winbindd</command> to write status information to the winbind
 445                 log file including information about the number of user and
 446                 group ids allocated by <command>winbindd</command>.</para>
 447
 448                 <para>Log files are stored in the filename specified by the
 449                 log file parameter.</para></listitem>
 450                 </varlistentry>
 451         </variablelist>
 452 </refsect1>
 453
 454 <refsect1>
 455         <title>FILES</title>
 456
 457         <variablelist>
 458                 <varlistentry>
 459                 <term><filename>/etc/nsswitch.conf(5)</filename></term>
 460                 <listitem><para>Name service switch configuration file.</para>
 461                 </listitem>
 462                 </varlistentry>
 463
 464                 <varlistentry>
 465                 <term>/tmp/.winbindd/pipe</term>
 466                 <listitem><para>The UNIX pipe over which clients communicate with
 467                 the <command>winbindd</command> program.  For security reasons, the
 468                 winbind client will only attempt to connect to the winbindd daemon
 469                 if both the <filename>/tmp/.winbindd</filename> directory
 470                 and <filename>/tmp/.winbindd/pipe</filename> file are owned by
 471                 root. </para></listitem>
 472                 </varlistentry>
 473
 474                 <varlistentry>
 475                 <term>/lib/libnss_winbind.so.X</term>
 476                 <listitem><para>Implementation of name service switch library.
 477                 </para></listitem>
 478                 </varlistentry>
 479
 480                 <varlistentry>
 481                 <term>$LOCKDIR/winbindd_idmap.tdb</term>
 482                 <listitem><para>Storage for the Windows NT rid to UNIX user/group
 483                 id mapping.  The lock directory is specified when Samba is initially
 484                 compiled using the <parameter>--with-lockdir</parameter> option.
 485                 This directory is by default <filename>/usr/local/samba/var/locks
 486                 </filename>. </para></listitem>
 487                 </varlistentry>
 488
 489                 <varlistentry>
 490                 <term>$LOCKDIR/winbindd_cache.tdb</term>
 491                 <listitem><para>Storage for cached user and group information.
 492                 </para></listitem>
 493                 </varlistentry>
 494         </variablelist>
 495 </refsect1>
 496
 497
 498 <refsect1>
 499         <title>VERSION</title>
 500
 501         <para>This man page is correct for version 2.2 of
 502         the Samba suite.</para>
 503 </refsect1>
 504
 505 <refsect1>
 506         <title>SEE ALSO</title>
 507
 508         <para><filename>nsswitch.conf(5)</filename>,
 509         <ulink url="samba.7.html">samba(7)</ulink>,
 510         <ulink url="wbinfo.1.html">wbinfo(1)</ulink>,
 511         <ulink url="smb.conf.5.html">smb.conf(5)</ulink></para>
 512 </refsect1>
 513
 514 <refsect1>
 515         <title>AUTHOR</title>
 516
 517         <para>The original Samba software and related utilities
 518         were created by Andrew Tridgell. Samba is now developed
 519         by the Samba Team as an Open Source project similar
 520         to the way the Linux kernel is developed.</para>
 521
 522         <para><command>wbinfo</command> and <command>winbindd</command>
 523         were written by Tim Potter.</para>
 524
 525         <para>The conversion to DocBook for Samba 2.2 was done
 526         by Gerald Carter</para>
 527 </refsect1>
 528
 529 </refentry>