large collection of minor fixes. Mostly typos
[Samba.git] / docs / htmldocs / winbindd.8.html
blobad54228a6f4d8ca90a5a129e6a710c586d017995
1 <HTML
2 ><HEAD
3 ><TITLE
4 >winbindd</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.57"></HEAD
8 ><BODY
9 CLASS="REFENTRY"
10 BGCOLOR="#FFFFFF"
11 TEXT="#000000"
12 LINK="#0000FF"
13 VLINK="#840084"
14 ALINK="#0000FF"
15 ><H1
16 ><A
17 NAME="WINBINDD"
18 >winbindd</A
19 ></H1
20 ><DIV
21 CLASS="REFNAMEDIV"
22 ><A
23 NAME="AEN5"
24 ></A
25 ><H2
26 >Name</H2
27 >winbindd&nbsp;--&nbsp;Name Service Switch daemon for resolving names
28 from NT servers</DIV
29 ><DIV
30 CLASS="REFSYNOPSISDIV"
31 ><A
32 NAME="AEN8"
33 ></A
34 ><H2
35 >Synopsis</H2
36 ><P
37 ><B
38 CLASS="COMMAND"
39 >winbindd</B
40 > [-i] [-d &#60;debug level&#62;] [-s &#60;smb config file&#62;]</P
41 ></DIV
42 ><DIV
43 CLASS="REFSECT1"
44 ><A
45 NAME="AEN14"
46 ></A
47 ><H2
48 >DESCRIPTION</H2
49 ><P
50 >This program is part of the <A
51 HREF="samba.7.html"
52 TARGET="_top"
53 > Samba</A
54 > suite.</P
55 ><P
56 ><B
57 CLASS="COMMAND"
58 >winbindd</B
59 > is a daemon that provides
60 a service for the Name Service Switch capability that is present
61 in most modern C libraries. The Name Service Switch allows user
62 and system information to be obtained from different databases
63 services such as NIS or DNS. The exact behaviour can be configured
64 throught the <TT
65 CLASS="FILENAME"
66 >/etc/nsswitch.conf</TT
67 > file.
68 Users and groups are allocated as they are resolved to a range
69 of user and group ids specified by the administrator of the
70 Samba system.</P
71 ><P
72 >The service provided by <B
73 CLASS="COMMAND"
74 >winbindd</B
75 > is called `winbind' and
76 can be used to resolve user and group information from a
77 Windows NT server. The service can also provide authentication
78 services via an associated PAM module. </P
79 ><P
80 >The following nsswitch databases are implemented by
81 the winbindd service: </P
82 ><P
83 ></P
84 ><DIV
85 CLASS="VARIABLELIST"
86 ><DL
87 ><DT
88 >passwd</DT
89 ><DD
90 ><P
91 >User information traditionally stored in
92 the <TT
93 CLASS="FILENAME"
94 >passwd(5)</TT
95 > file and used by
97 CLASS="COMMAND"
98 >getpwent(3)</B
99 > functions. </P
100 ></DD
101 ><DT
102 >group</DT
103 ><DD
105 >Group information traditionally stored in
106 the <TT
107 CLASS="FILENAME"
108 >group(5)</TT
109 > file and used by
111 CLASS="COMMAND"
112 >getgrent(3)</B
113 > functions. </P
114 ></DD
115 ></DL
116 ></DIV
118 >For example, the following simple configuration in the
120 CLASS="FILENAME"
121 >/etc/nsswitch.conf</TT
122 > file can be used to initially
123 resolve user and group information from <TT
124 CLASS="FILENAME"
125 >/etc/passwd
126 </TT
127 > and <TT
128 CLASS="FILENAME"
129 >/etc/group</TT
130 > and then from the
131 Windows NT server. </P
133 ><TABLE
134 BORDER="0"
135 BGCOLOR="#E0E0E0"
136 WIDTH="100%"
137 ><TR
138 ><TD
139 ><PRE
140 CLASS="PROGRAMLISTING"
141 >passwd: files winbind
142 group: files winbind
143 </PRE
144 ></TD
145 ></TR
146 ></TABLE
147 ></P
148 ></DIV
149 ><DIV
150 CLASS="REFSECT1"
152 NAME="AEN43"
153 ></A
154 ><H2
155 >OPTIONS</H2
157 ></P
158 ><DIV
159 CLASS="VARIABLELIST"
160 ><DL
161 ><DT
162 >-d debuglevel</DT
163 ><DD
165 >Sets the debuglevel to an integer between
166 0 and 100. 0 is for no debugging and 100 is for reams and
167 reams. To submit a bug report to the Samba Team, use debug
168 level 100 (see BUGS.txt). </P
169 ></DD
170 ><DT
171 >-i</DT
172 ><DD
174 >Tells <B
175 CLASS="COMMAND"
176 >winbindd</B
177 > to not
178 become a daemon and detach from the current terminal. This
179 option is used by developers when interactive debugging
180 of <B
181 CLASS="COMMAND"
182 >winbindd</B
183 > is required. </P
184 ></DD
185 ></DL
186 ></DIV
187 ></DIV
188 ><DIV
189 CLASS="REFSECT1"
191 NAME="AEN56"
192 ></A
193 ><H2
194 >NAME AND ID RESOLUTION</H2
196 >Users and groups on a Windows NT server are assigned
197 a relative id (rid) which is unique for the domain 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 rids and unix user
200 and group ids is required. This is one of the jobs that <B
201 CLASS="COMMAND"
202 > winbindd</B
203 > performs. </P
205 >As winbindd users and groups are resolved from a server, user
206 and group ids are allocated from a specified range. This
207 is done on a first come, first served basis, although all existing
208 users and groups will be mapped as soon as a client performs a user
209 or group enumeration command. The allocated unix ids are stored
210 in a database file under the Samba lock directory and will be
211 remembered. </P
213 >WARNING: The rid to unix id database is the only location
214 where the user and group mappings are stored by winbindd. If this
215 file is deleted or corrupted, there is no way for winbindd to
216 determine which user and group ids correspond to Windows NT user
217 and group rids. </P
218 ></DIV
219 ><DIV
220 CLASS="REFSECT1"
222 NAME="AEN62"
223 ></A
224 ><H2
225 >CONFIGURATION</H2
227 >Configuration of the <B
228 CLASS="COMMAND"
229 >winbindd</B
230 > daemon
231 is done through configuration parameters in the <TT
232 CLASS="FILENAME"
233 >smb.conf(5)
234 </TT
235 > file. All parameters should be specified in the
236 [global] section of smb.conf. </P
238 ></P
239 ><DIV
240 CLASS="VARIABLELIST"
241 ><DL
242 ><DT
243 >winbind separator</DT
244 ><DD
246 >The winbind separator option allows you
247 to specify how NT domain names and user names are combined
248 into unix user names when presented to users. By default,
250 CLASS="COMMAND"
251 >winbindd</B
252 > will use the traditional '\'
253 separator so that the unix user names look like
254 DOMAIN\username. In some cases this separator character may
255 cause problems as the '\' character has special meaning in
256 unix shells. In that case you can use the winbind separator
257 option to specify an alternative separator character. Good
258 alternatives may be '/' (although that conflicts
259 with the unix directory separator) or a '+ 'character.
260 The '+' character appears to be the best choice for 100%
261 compatibility with existing unix utilities, but may be an
262 aesthetically bad choice depending on your taste. </P
264 >Default: <B
265 CLASS="COMMAND"
266 >winbind separator = \ </B
270 >Example: <B
271 CLASS="COMMAND"
272 >winbind separator = + </B
273 ></P
274 ></DD
275 ><DT
276 >winbind uid</DT
277 ><DD
279 >The winbind uid parameter specifies the
280 range of user ids that are allocated by the winbindd daemon.
281 This range of ids should have no existing local or NIS users
282 within it as strange conflicts can occur otherwise. </P
284 >Default: <B
285 CLASS="COMMAND"
286 >winbind uid = &#60;empty string&#62;
288 ></P
290 >Example: <B
291 CLASS="COMMAND"
292 >winbind uid = 10000-20000</B
293 ></P
294 ></DD
295 ><DT
296 >winbind gid</DT
297 ><DD
299 >The winbind gid parameter specifies the
300 range of group ids that are allocated by the winbindd daemon.
301 This range of group ids should have no existing local or NIS
302 groups within it as strange conflicts can occur otherwise.</P
304 >Default: <B
305 CLASS="COMMAND"
306 >winbind gid = &#60;empty string&#62;
308 ></P
310 >Example: <B
311 CLASS="COMMAND"
312 >winbind gid = 10000-20000
314 > </P
315 ></DD
316 ><DT
317 >winbind cache time</DT
318 ><DD
320 >This parameter specifies the number of
321 seconds the winbindd daemon will cache user and group information
322 before querying a Windows NT server again. When a item in the
323 cache is older than this time winbindd will ask the domain
324 controller for the sequence number of the server's account database.
325 If the sequence number has not changed then the cached item is
326 marked as valid for a further <TT
327 CLASS="PARAMETER"
329 >winbind cache time
331 ></TT
332 > seconds. Otherwise the item is fetched from the
333 server. This means that as long as the account database is not
334 actively changing winbindd will only have to send one sequence
335 number query packet every <TT
336 CLASS="PARAMETER"
338 >winbind cache time
340 ></TT
341 > seconds. </P
343 >Default: <B
344 CLASS="COMMAND"
345 >winbind cache time = 15</B
348 ></DD
349 ><DT
350 >winbind enum users</DT
351 ><DD
353 >On large installations it may be necessary
354 to suppress the enumeration of users through the <B
355 CLASS="COMMAND"
356 > setpwent()</B
357 >, <B
358 CLASS="COMMAND"
359 >getpwent()</B
360 > and
362 CLASS="COMMAND"
363 >endpwent()</B
364 > group of system calls. If
365 the <TT
366 CLASS="PARAMETER"
368 >winbind enum users</I
369 ></TT
370 > parameter is false,
371 calls to the <B
372 CLASS="COMMAND"
373 >getpwent</B
374 > system call will not
375 return any data. </P
377 ><EM
378 >Warning:</EM
379 > Turning off user enumeration
380 may cause some programs to behave oddly. For example, the <B
381 CLASS="COMMAND"
382 >finger</B
384 program relies on having access to the full user list when
385 searching for matching usernames. </P
387 >Default: <B
388 CLASS="COMMAND"
389 >winbind enum users = yes </B
390 ></P
391 ></DD
392 ><DT
393 >winbind enum groups</DT
394 ><DD
396 >On large installations it may be necessary
397 to suppress the enumeration of groups through the <B
398 CLASS="COMMAND"
399 > setgrent()</B
400 >, <B
401 CLASS="COMMAND"
402 >getgrent()</B
403 > and
405 CLASS="COMMAND"
406 >endgrent()</B
407 > group of system calls. If
408 the <TT
409 CLASS="PARAMETER"
411 >winbind enum groups</I
412 ></TT
413 > parameter is
414 false, calls to the <B
415 CLASS="COMMAND"
416 >getgrent()</B
417 > system
418 call will not return any data. </P
420 ><EM
421 >Warning:</EM
422 > Turning off group
423 enumeration may cause some programs to behave oddly.
426 >Default: <B
427 CLASS="COMMAND"
428 >winbind enum groups = no </B
431 ></DD
432 ><DT
433 >template homedir</DT
434 ><DD
436 >When filling out the user information
437 for a Windows NT user, the <B
438 CLASS="COMMAND"
439 >winbindd</B
440 > daemon
441 uses this parameter to fill in the home directory for that user.
442 If the string <TT
443 CLASS="PARAMETER"
445 >%D</I
446 ></TT
447 > is present it is
448 substituted with the user's Windows NT domain name. If the
449 string <TT
450 CLASS="PARAMETER"
452 >%U</I
453 ></TT
454 > is present it is substituted
455 with the user's Windows NT user name. </P
457 >Default: <B
458 CLASS="COMMAND"
459 >template homedir = /home/%D/%U </B
462 ></DD
463 ><DT
464 >template shell</DT
465 ><DD
467 >When filling out the user information for
468 a Windows NT user, the <B
469 CLASS="COMMAND"
470 >winbindd</B
471 > daemon
472 uses this parameter to fill in the shell for that user.
475 >Default: <B
476 CLASS="COMMAND"
477 >template shell = /bin/false </B
480 ></DD
481 ></DL
482 ></DIV
483 ></DIV
484 ><DIV
485 CLASS="REFSECT1"
487 NAME="AEN144"
488 ></A
489 ><H2
490 >EXAMPLE SETUP</H2
492 >To setup winbindd for user and group lookups plus
493 authentication from a domain controller use something like the
494 following setup. This was tested on a RedHat 6.2 Linux box. </P
496 >In <TT
497 CLASS="FILENAME"
498 >/etc/nsswitch.conf</TT
499 > put the
500 following:</P
502 ><TABLE
503 BORDER="0"
504 BGCOLOR="#E0E0E0"
505 WIDTH="100%"
506 ><TR
507 ><TD
508 ><PRE
509 CLASS="PROGRAMLISTING"
510 >passwd: files winbind
511 group: files winbind
512 </PRE
513 ></TD
514 ></TR
515 ></TABLE
516 ></P
518 >In <TT
519 CLASS="FILENAME"
520 >/etc/pam.d/*</TT
521 > replace the
523 CLASS="PARAMETER"
525 >auth</I
526 ></TT
527 > lines with something like this: </P
529 ><TABLE
530 BORDER="0"
531 BGCOLOR="#E0E0E0"
532 WIDTH="100%"
533 ><TR
534 ><TD
535 ><PRE
536 CLASS="PROGRAMLISTING"
537 >auth required /lib/security/pam_securetty.so
538 auth required /lib/security/pam_nologin.so
539 auth sufficient /lib/security/pam_winbind.so
540 auth required /lib/security/pam_pwdb.so use_first_pass shadow nullok
541 </PRE
542 ></TD
543 ></TR
544 ></TABLE
545 ></P
547 >Note in particular the use of the <TT
548 CLASS="PARAMETER"
550 >sufficient</I
551 ></TT
553 keyword and the <TT
554 CLASS="PARAMETER"
556 >use_first_pass</I
557 ></TT
558 > keyword. </P
560 >Now replace the account lines with this: </P
563 CLASS="COMMAND"
564 >account required /lib/security/pam_winbind.so
566 ></P
568 >The next step is to join the domain. To do that use the
570 CLASS="COMMAND"
571 >smbpasswd</B
572 > program like this: </P
575 CLASS="COMMAND"
576 >smbpasswd -j DOMAIN -r PDC -U
577 Administrator</B
578 ></P
580 >The username after the <TT
581 CLASS="PARAMETER"
583 >-U</I
584 ></TT
585 > can be any
586 Domain user that has administrator privileges on the machine.
587 Substitute your domain name for "DOMAIN" and the name of your PDC
588 for "PDC".</P
590 >Next copy <TT
591 CLASS="FILENAME"
592 >libnss_winbind.so</TT
593 > to
595 CLASS="FILENAME"
596 >/lib</TT
597 > and <TT
598 CLASS="FILENAME"
599 >pam_winbind.so</TT
601 to <TT
602 CLASS="FILENAME"
603 >/lib/security</TT
604 >. A symbolic link needs to be
605 made from <TT
606 CLASS="FILENAME"
607 >/lib/libnss_winbind.so</TT
608 > to
610 CLASS="FILENAME"
611 >/lib/libnss_winbind.so.2</TT
612 >. If you are using an
613 older version of glibc then the target of the link should be
615 CLASS="FILENAME"
616 >/lib/libnss_winbind.so.1</TT
617 >.</P
619 >Finally, setup a <TT
620 CLASS="FILENAME"
621 >smb.conf</TT
622 > containing directives like the
623 following: </P
625 ><TABLE
626 BORDER="0"
627 BGCOLOR="#E0E0E0"
628 WIDTH="100%"
629 ><TR
630 ><TD
631 ><PRE
632 CLASS="PROGRAMLISTING"
633 >[global]
634 winbind separator = +
635 winbind cache time = 10
636 template shell = /bin/bash
637 template homedir = /home/%D/%U
638 winbind uid = 10000-20000
639 winbind gid = 10000-20000
640 workgroup = DOMAIN
641 security = domain
642 password server = *
643 </PRE
644 ></TD
645 ></TR
646 ></TABLE
647 ></P
649 >Now start winbindd and you should find that your user and
650 group database is expanded to include your NT users and groups,
651 and that you can login to your unix box as a domain user, using
652 the DOMAIN+user syntax for the username. You may wish to use the
653 commands <B
654 CLASS="COMMAND"
655 >getent passwd</B
656 > and <B
657 CLASS="COMMAND"
658 >getent group
660 > to confirm the correct operation of winbindd.</P
661 ></DIV
662 ><DIV
663 CLASS="REFSECT1"
665 NAME="AEN183"
666 ></A
667 ><H2
668 >NOTES</H2
670 >The following notes are useful when configuring and
671 running <B
672 CLASS="COMMAND"
673 >winbindd</B
674 >: </P
677 CLASS="COMMAND"
678 >nmbd</B
679 > must be running on the local machine
680 for <B
681 CLASS="COMMAND"
682 >winbindd</B
683 > to work. <B
684 CLASS="COMMAND"
685 >winbindd</B
687 queries the list of trusted domains for the Windows NT server
688 on startup and when a SIGHUP is received. Thus, for a running <B
689 CLASS="COMMAND"
690 > winbindd</B
691 > to become aware of new trust relationships between
692 servers, it must be sent a SIGHUP signal. </P
694 >Client processes resolving names through the <B
695 CLASS="COMMAND"
696 >winbindd</B
698 nsswitch module read an environment variable named <TT
699 CLASS="ENVAR"
700 > $WINBINDD_DOMAIN</TT
701 >. If this variable contains a comma separated
702 list of Windows NT domain names, then winbindd will only resolve users
703 and groups within those Windows NT domains. </P
705 >PAM is really easy to misconfigure. Make sure you know what
706 you are doing when modifying PAM configuration files. It is possible
707 to set up PAM such that you can no longer log into your system. </P
709 >If more than one UNIX machine is running <B
710 CLASS="COMMAND"
711 >winbindd</B
713 then in general the user and groups ids allocated by winbindd will not
714 be the same. The user and group ids will only be valid for the local
715 machine.</P
717 >If the the Windows NT RID to UNIX user and group id mapping
718 file is damaged or destroyed then the mappings will be lost. </P
719 ></DIV
720 ><DIV
721 CLASS="REFSECT1"
723 NAME="AEN199"
724 ></A
725 ><H2
726 >SIGNALS</H2
728 >The following signals can be used to manipulate the
730 CLASS="COMMAND"
731 >winbindd</B
732 > daemon. </P
734 ></P
735 ><DIV
736 CLASS="VARIABLELIST"
737 ><DL
738 ><DT
739 >SIGHUP</DT
740 ><DD
742 >Reload the <TT
743 CLASS="FILENAME"
744 >smb.conf(5)</TT
746 file and apply any parameter changes to the running
747 version of winbindd. This signal also clears any cached
748 user and group information. The list of other domains trusted
749 by winbindd is also reloaded. </P
750 ></DD
751 ><DT
752 >SIGUSR1</DT
753 ><DD
755 >The SIGUSR1 signal will cause <B
756 CLASS="COMMAND"
757 > winbindd</B
758 > to write status information to the winbind
759 log file including information about the number of user and
760 group ids allocated by <B
761 CLASS="COMMAND"
762 >winbindd</B
763 >.</P
765 >Log files are stored in the filename specified by the
766 log file parameter.</P
767 ></DD
768 ></DL
769 ></DIV
770 ></DIV
771 ><DIV
772 CLASS="REFSECT1"
774 NAME="AEN216"
775 ></A
776 ><H2
777 >FILES</H2
779 ></P
780 ><DIV
781 CLASS="VARIABLELIST"
782 ><DL
783 ><DT
784 ><TT
785 CLASS="FILENAME"
786 >/etc/nsswitch.conf(5)</TT
787 ></DT
788 ><DD
790 >Name service switch configuration file.</P
791 ></DD
792 ><DT
793 >/tmp/.winbindd/pipe</DT
794 ><DD
796 >The UNIX pipe over which clients communicate with
797 the <B
798 CLASS="COMMAND"
799 >winbindd</B
800 > program. For security reasons, the
801 winbind client will only attempt to connect to the winbindd daemon
802 if both the <TT
803 CLASS="FILENAME"
804 >/tmp/.winbindd</TT
805 > directory
806 and <TT
807 CLASS="FILENAME"
808 >/tmp/.winbindd/pipe</TT
809 > file are owned by
810 root. </P
811 ></DD
812 ><DT
813 >/lib/libnss_winbind.so.X</DT
814 ><DD
816 >Implementation of name service switch library.
818 ></DD
819 ><DT
820 >$LOCKDIR/winbindd_idmap.tdb</DT
821 ><DD
823 >Storage for the Windows NT rid to UNIX user/group
824 id mapping. The lock directory is specified when Samba is initially
825 compiled using the <TT
826 CLASS="PARAMETER"
828 >--with-lockdir</I
829 ></TT
830 > option.
831 This directory is by default <TT
832 CLASS="FILENAME"
833 >/usr/local/samba/var/locks
834 </TT
835 >. </P
836 ></DD
837 ><DT
838 >$LOCKDIR/winbindd_cache.tdb</DT
839 ><DD
841 >Storage for cached user and group information.
843 ></DD
844 ></DL
845 ></DIV
846 ></DIV
847 ><DIV
848 CLASS="REFSECT1"
850 NAME="AEN245"
851 ></A
852 ><H2
853 >VERSION</H2
855 >This man page is correct for version 2.2 of
856 the Samba suite.</P
857 ></DIV
858 ><DIV
859 CLASS="REFSECT1"
861 NAME="AEN248"
862 ></A
863 ><H2
864 >SEE ALSO</H2
866 ><TT
867 CLASS="FILENAME"
868 >nsswitch.conf(5)</TT
871 HREF="samba.7.html"
872 TARGET="_top"
873 >samba(7)</A
876 HREF="wbinfo.1.html"
877 TARGET="_top"
878 >wbinfo(1)</A
881 HREF="smb.conf.5.html"
882 TARGET="_top"
883 >smb.conf(5)</A
884 ></P
885 ></DIV
886 ><DIV
887 CLASS="REFSECT1"
889 NAME="AEN255"
890 ></A
891 ><H2
892 >AUTHOR</H2
894 >The original Samba software and related utilities
895 were created by Andrew Tridgell. Samba is now developed
896 by the Samba Team as an Open Source project similar
897 to the way the Linux kernel is developed.</P
900 CLASS="COMMAND"
901 >wbinfo</B
902 > and <B
903 CLASS="COMMAND"
904 >winbindd</B
906 were written by Tim Potter.</P
908 >The conversion to DocBook for Samba 2.2 was done
909 by Gerald Carter</P
910 ></DIV
911 ></BODY
912 ></HTML