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