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