updated Makefile to use the ldp DSSSL and regenerated all docs.
[Samba.git] / docs / htmldocs / winbindd.8.html
blob0080386ee4d8d3d437ca2169510eb69d8892e12f
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 >nmblookup</B
40 > [-d debuglevel] [-i] [-S] [-r] [-A] [-h] [-B &#60;broadcast address&#62;] [-U &#60;unicast address&#62;] [-d &#60;debug level&#62;] [-s &#60;smb config file&#62;] [-i &#60;NetBIOS scope&#62;] [-T] {name}</P
41 ></DIV
42 ><DIV
43 CLASS="REFSECT1"
44 ><A
45 NAME="AEN24"
46 ></A
47 ><H2
48 >DESCRIPTION</H2
49 ><P
50 >This tool is part of the <A
51 HREF="samba.7.html"
52 TARGET="_top"
53 > Samba</A
54 > suite version 3.0 and describes functionality not
55 yet implemented in the main version of Samba.</P
56 ><P
57 ><B
58 CLASS="COMMAND"
59 >winbindd</B
60 > is a daemon that provides
61 a service for the Name Service Switch capability that is present
62 in most modern C libraries. The Name Service Switch allows user
63 and system information to be obtained from different databases
64 services such as NIS or DNS. The exact behaviour can be configured
65 throught the <TT
66 CLASS="FILENAME"
67 >/etc/nsswitch.conf</TT
68 > file.
69 Users and groups are allocated as they are resolved to a range
70 of user and group ids specified by the administrator of the
71 Samba system.</P
72 ><P
73 >The service provided by winbindd is called `winbind' and
74 can be used to resolve user and group information from a
75 Windows NT server. The service can also provide authentication
76 services via an associated PAM module. </P
77 ><P
78 >The following nsswitch databases are implemented by
79 the winbindd service: </P
80 ><P
81 ></P
82 ><DIV
83 CLASS="VARIABLELIST"
84 ><DL
85 ><DT
86 >passwd</DT
87 ><DD
88 ><P
89 >User information traditionally stored in
90 the <TT
91 CLASS="FILENAME"
92 >passwd(5)</TT
93 > file and used by
95 CLASS="COMMAND"
96 >getpwent(3)</B
97 > functions. </P
98 ></DD
99 ><DT
100 >group</DT
101 ><DD
103 >Group information traditionally stored in
104 the <TT
105 CLASS="FILENAME"
106 >group(5)</TT
107 > file and used by
109 CLASS="COMMAND"
110 >getgrent(3)</B
111 > functions. </P
112 ></DD
113 ></DL
114 ></DIV
116 >For example, the following simple configuration in the
118 CLASS="FILENAME"
119 >/etc/nsswitch.conf</TT
120 > file can be used to initially
121 resolve user and group information from <TT
122 CLASS="FILENAME"
123 >/etc/passwd
124 </TT
125 > and <TT
126 CLASS="FILENAME"
127 >/etc/group</TT
128 > and then from the
129 Windows NT server. </P
131 ><TABLE
132 BORDER="0"
133 BGCOLOR="#E0E0E0"
134 WIDTH="100%"
135 ><TR
136 ><TD
137 ><PRE
138 CLASS="PROGRAMLISTING"
139 >passwd: files winbind
140 group: files winbind
141 </PRE
142 ></TD
143 ></TR
144 ></TABLE
145 ></P
146 ></DIV
147 ><DIV
148 CLASS="REFSECT1"
150 NAME="AEN52"
151 ></A
152 ><H2
153 >OPTIONS</H2
155 ></P
156 ><DIV
157 CLASS="VARIABLELIST"
158 ><DL
159 ><DT
160 >-d debuglevel</DT
161 ><DD
163 >Sets the debuglevel to an integer between
164 0 and 100. 0 is for no debugging and 100 is for reams and
165 reams. To submit a bug report to the Samba Team, use debug
166 level 100 (see BUGS.txt). </P
167 ></DD
168 ><DT
169 >-i</DT
170 ><DD
172 >Tells <B
173 CLASS="COMMAND"
174 >winbindd</B
175 > to not
176 become a daemon and detach from the current terminal. This
177 option is used by developers when interactive debugging
178 of <B
179 CLASS="COMMAND"
180 >winbindd</B
181 > is required. </P
182 ></DD
183 ></DL
184 ></DIV
185 ></DIV
186 ><DIV
187 CLASS="REFSECT1"
189 NAME="AEN65"
190 ></A
191 ><H2
192 >NAME AND ID RESOLUTION</H2
194 >Users and groups on a Windows NT server are assigned
195 a relative id (rid) which is unique for the domain when the
196 user or group is created. To convert the Windows NT user or group
197 into a unix user or group, a mapping between rids and unix user
198 and group ids is required. This is one of the jobs that <B
199 CLASS="COMMAND"
200 > winbindd</B
201 > performs. </P
203 >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. </P
211 >WARNING: The rid 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. </P
216 ></DIV
217 ><DIV
218 CLASS="REFSECT1"
220 NAME="AEN71"
221 ></A
222 ><H2
223 >CONFIGURATION</H2
225 >Configuration of the <B
226 CLASS="COMMAND"
227 >winbindd</B
228 > daemon
229 is done through configuration parameters in the <TT
230 CLASS="FILENAME"
231 >smb.conf(5)
232 </TT
233 > file. All parameters should be specified in the
234 [global] section of smb.conf. </P
236 ></P
237 ><DIV
238 CLASS="VARIABLELIST"
239 ><DL
240 ><DT
241 >winbind separator</DT
242 ><DD
244 >The winbind separator option allows you
245 to specify how NT domain names and user names are combined
246 into unix user names when presented to users. By default,
248 CLASS="COMMAND"
249 >winbindd</B
250 > will use the traditional '\'
251 separator so that the unix user names look like
252 DOMAIN\username. In some cases this separator character may
253 cause problems as the '\' character has special meaning in
254 unix shells. In that case you can use the winbind separator
255 option to specify an alternative sepataror character. Good
256 alternatives may be '/' (although that conflicts
257 with the unix directory separator) or a '+ 'character.
258 The '+' character appears to be the best choice for 100%
259 compatibility with existing unix utilities, but may be an
260 aesthetically bad choice depending on your taste. </P
262 >Default: <B
263 CLASS="COMMAND"
264 >winbind separator = \ </B
268 >Example: <B
269 CLASS="COMMAND"
270 >winbind separator = + </B
271 ></P
272 ></DD
273 ><DT
274 >winbind uid</DT
275 ><DD
277 >The winbind uid parameter specifies the
278 range of user ids that are allocated by the winbindd daemon.
279 This range of ids should have no existing local or nis users
280 within it as strange conflicts can occur otherwise. </P
282 >Default: <B
283 CLASS="COMMAND"
284 >winbind uid = &#60;empty string&#62;
286 ></P
288 >Example: <B
289 CLASS="COMMAND"
290 >winbind uid = 10000-20000</B
291 ></P
292 ></DD
293 ><DT
294 >winbind gid</DT
295 ><DD
297 >The winbind gid parameter specifies the
298 range of group ids that are allocated by the winbindd daemon.
299 This range of group ids should have no existing local or nis
300 groups within it as strange conflicts can occur otherwise.</P
302 >Default: <B
303 CLASS="COMMAND"
304 >winbind gid = &#60;empty string&#62;
306 ></P
308 >Example: <B
309 CLASS="COMMAND"
310 >winbind gid = 10000-20000
312 > </P
313 ></DD
314 ><DT
315 >winbind cache time</DT
316 ><DD
318 >This parameter specifies the number of
319 seconds the winbindd daemon will cache user and group information
320 before querying a Windows NT server again. When a item in the
321 cache is older than this time winbindd will ask the domain
322 controller for the sequence number of the servers account database.
323 If the sequence number has not changed then the cached item is
324 marked as valid for a further <TT
325 CLASS="PARAMETER"
327 >winbind cache time
329 ></TT
330 > seconds. Otherwise the item is fetched from the
331 server. This means that as long as the account database is not
332 actively changing winbindd will only have to send one sequence
333 number query packet every <TT
334 CLASS="PARAMETER"
336 >winbind cache time
338 ></TT
339 > seconds. </P
341 >Default: <B
342 CLASS="COMMAND"
343 >winbind cache time = 15</B
346 ></DD
347 ><DT
348 >winbind enum users</DT
349 ><DD
351 >On large installations it may be necessary
352 to suppress the enumeration of users through the <B
353 CLASS="COMMAND"
354 > setpwent()</B
355 >, <B
356 CLASS="COMMAND"
357 >getpwent()</B
358 > and
360 CLASS="COMMAND"
361 >endpwent()</B
362 > group of system calls. If
363 the <TT
364 CLASS="PARAMETER"
366 >winbind enum users</I
367 ></TT
368 > parameter is false,
369 calls to the <B
370 CLASS="COMMAND"
371 >getpwent</B
372 > system call will not
373 return any data. </P
375 ><EM
376 >Warning:</EM
377 > Turning off user enumeration
378 may cause some programs to behave oddly. For example, the finger
379 program relies on having access to the full user list when
380 searching for matching usernames. </P
382 >Default: <B
383 CLASS="COMMAND"
384 >winbind enum users = yes </B
385 ></P
386 ></DD
387 ><DT
388 >winbind enum groups</DT
389 ><DD
391 >On large installations it may be necessary
392 to suppress the enumeration of groups through the <B
393 CLASS="COMMAND"
394 > setgrent()</B
395 >, <B
396 CLASS="COMMAND"
397 >getgrent()</B
398 > and
400 CLASS="COMMAND"
401 >endgrent()</B
402 > group of system calls. If
403 the <TT
404 CLASS="PARAMETER"
406 >winbind enum groups</I
407 ></TT
408 > parameter is
409 false, calls to the <B
410 CLASS="COMMAND"
411 >getgrent()</B
412 > system
413 call will not return any data. </P
415 ><EM
416 >Warning:</EM
417 > Turning off group
418 enumeration may cause some programs to behave oddly.
421 >Default: <B
422 CLASS="COMMAND"
423 >winbind enum groups = no </B
426 ></DD
427 ><DT
428 >template homedir</DT
429 ><DD
431 >When filling out the user information
432 for a Windows NT user, the <B
433 CLASS="COMMAND"
434 >winbindd</B
435 > daemon
436 uses this parameter to fill in the home directory for that user.
437 If the string <TT
438 CLASS="PARAMETER"
440 >%D</I
441 ></TT
442 > is present it is
443 substituted with the user's Windows NT domain name. If the
444 string <TT
445 CLASS="PARAMETER"
447 >%U</I
448 ></TT
449 > is present it is substituted
450 with the user's Windows NT user name. </P
452 >Default: <B
453 CLASS="COMMAND"
454 >template homedir = /home/%D/%U </B
457 ></DD
458 ><DT
459 >template shell</DT
460 ><DD
462 >When filling out the user information for
463 a Windows NT user, the <B
464 CLASS="COMMAND"
465 >winbindd</B
466 > daemon
467 uses this parameter to fill in the shell for that user.
470 >Default: <B
471 CLASS="COMMAND"
472 >template shell = /bin/false </B
475 ></DD
476 ></DL
477 ></DIV
478 ></DIV
479 ><DIV
480 CLASS="REFSECT1"
482 NAME="AEN152"
483 ></A
484 ><H2
485 >EXAMPLE SETUP</H2
487 >To setup winbindd for user and group lookups plus
488 authentication from a domain controller use something like the
489 following setup. This was tested on a RedHat 6.2 Linux box. </P
491 >In <TT
492 CLASS="FILENAME"
493 >/etc/nsswitch.conf</TT
494 > put the
495 following:</P
497 ><TABLE
498 BORDER="0"
499 BGCOLOR="#E0E0E0"
500 WIDTH="100%"
501 ><TR
502 ><TD
503 ><PRE
504 CLASS="PROGRAMLISTING"
505 >passwd: files winbind
506 group: files winbind
507 </PRE
508 ></TD
509 ></TR
510 ></TABLE
511 ></P
513 >In <TT
514 CLASS="FILENAME"
515 >/etc/pam.d/*</TT
516 > replace the
518 CLASS="PARAMETER"
520 >auth</I
521 ></TT
522 > lines with something like this: </P
524 ><TABLE
525 BORDER="0"
526 BGCOLOR="#E0E0E0"
527 WIDTH="100%"
528 ><TR
529 ><TD
530 ><PRE
531 CLASS="PROGRAMLISTING"
532 >auth required /lib/security/pam_securetty.so
533 auth required /lib/security/pam_nologin.so
534 auth sufficient /lib/security/pam_winbind.so
535 auth required /lib/security/pam_pwdb.so use_first_pass shadow nullok
536 </PRE
537 ></TD
538 ></TR
539 ></TABLE
540 ></P
542 >Note in particular the use of the <TT
543 CLASS="PARAMETER"
545 >sufficient</I
546 ></TT
548 keyword and the <TT
549 CLASS="PARAMETER"
551 >use_first_pass</I
552 ></TT
553 > keyword. </P
555 >Now replace the account lines with this: </P
558 CLASS="COMMAND"
559 >account required /lib/security/pam_winbind.so
561 ></P
563 >The next step is to join the domain. To do that use the
565 CLASS="COMMAND"
566 >samedit</B
567 > program like this: </P
570 CLASS="COMMAND"
571 >samedit -S '*' -W DOMAIN -UAdministrator</B
572 ></P
574 >The username after the <TT
575 CLASS="PARAMETER"
577 >-U</I
578 ></TT
579 > can be any Domain
580 user that has administrator priviliges on the machine. Next from
581 within <B
582 CLASS="COMMAND"
583 >samedit</B
584 >, run the command: </P
587 CLASS="COMMAND"
588 >createuser MACHINE$ -j DOMAIN -L</B
589 ></P
591 >This assumes your domain is called "DOMAIN" and your Samba
592 workstation is called "MACHINE". </P
594 >Next copy <TT
595 CLASS="FILENAME"
596 >libnss_winbind.so.2</TT
597 > to
599 CLASS="FILENAME"
600 >/lib</TT
601 > and <TT
602 CLASS="FILENAME"
603 >pam_winbind.so</TT
605 to <TT
606 CLASS="FILENAME"
607 >/lib/security</TT
608 >.</P
610 >Finally, setup a smb.conf containing directives like the
611 following: </P
613 ><TABLE
614 BORDER="0"
615 BGCOLOR="#E0E0E0"
616 WIDTH="100%"
617 ><TR
618 ><TD
619 ><PRE
620 CLASS="PROGRAMLISTING"
621 >[global]
622 winbind separator = +
623 winbind cache time = 10
624 template shell = /bin/bash
625 template homedir = /home/%D/%U
626 winbind uid = 10000-20000
627 winbind gid = 10000-20000
628 workgroup = DOMAIN
629 security = domain
630 password server = *
631 </PRE
632 ></TD
633 ></TR
634 ></TABLE
635 ></P
637 >Now start winbindd and you should find that your user and
638 group database is expanded to include your NT users and groups,
639 and that you can login to your unix box as a domain user, using
640 the DOMAIN+user syntax for the username. You may wish to use the
641 commands <B
642 CLASS="COMMAND"
643 >getent passwd</B
644 > and <B
645 CLASS="COMMAND"
646 >getent group
648 > to confirm the correct operation of winbindd.</P
649 ></DIV
650 ><DIV
651 CLASS="REFSECT1"
653 NAME="AEN191"
654 ></A
655 ><H2
656 >Notes</H2
658 >The following notes are useful when configuring and
659 running <B
660 CLASS="COMMAND"
661 >winbindd</B
662 >: </P
665 CLASS="COMMAND"
666 >nmbd</B
667 > must be running on the local machine
668 for <B
669 CLASS="COMMAND"
670 >winbindd</B
671 > to work. <B
672 CLASS="COMMAND"
673 >winbindd</B
675 queries the list of trusted domains for the Windows NT server
676 on startup and when a SIGHUP is received. Thus, for a running <B
677 CLASS="COMMAND"
678 > winbindd</B
679 > to become aware of new trust relationships between
680 servers, it must be sent a SIGHUP signal. </P
682 >Client processes resolving names through the <B
683 CLASS="COMMAND"
684 >winbindd</B
686 nsswitch module read an environment variable named <TT
687 CLASS="PARAMETER"
689 > $WINBINDD_DOMAIN</I
690 ></TT
691 >. If this variable contains a comma separated
692 list of Windows NT domain names, then winbindd will only resolve users
693 and groups within those Windows NT domains. </P
695 >PAM is really easy to misconfigure. Make sure you know what
696 you are doing when modifying PAM configuration files. It is possible
697 to set up PAM such that you can no longer log into your system. </P
699 >If more than one UNIX machine is running <B
700 CLASS="COMMAND"
701 >winbindd</B
703 then in general the user and groups ids allocated by winbindd will not
704 be the same. The user and group ids will only be valid for the local
705 machine.</P
707 >If the the Windows NT RID to UNIX user and group id mapping
708 file is damaged or destroyed then the mappings will be lost. </P
709 ></DIV
710 ><DIV
711 CLASS="REFSECT1"
713 NAME="AEN207"
714 ></A
715 ><H2
716 >Signals</H2
718 >The following signals can be used to manipulate the
720 CLASS="COMMAND"
721 >winbindd</B
722 > daemon. </P
724 ></P
725 ><DIV
726 CLASS="VARIABLELIST"
727 ><DL
728 ><DT
729 >SIGHUP</DT
730 ><DD
732 >Reload the <TT
733 CLASS="FILENAME"
734 >smb.conf(5)</TT
736 file and apply any parameter changes to the running
737 version of winbindd. This signal also clears any cached
738 user and group information. The list of other domains trusted
739 by winbindd is also reloaded. </P
740 ></DD
741 ><DT
742 >SIGUSR1</DT
743 ><DD
745 >The SIGUSR1 signal will cause <B
746 CLASS="COMMAND"
747 > winbindd</B
748 > to write status information to the winbind
749 log file including information about the number of user and
750 group ids allocated by <B
751 CLASS="COMMAND"
752 >winbindd</B
753 >.</P
755 >Log files are stored in the filename specified by the
756 log file parameter.</P
757 ></DD
758 ></DL
759 ></DIV
760 ></DIV
761 ><DIV
762 CLASS="REFSECT1"
764 NAME="AEN224"
765 ></A
766 ><H2
767 >Files</H2
769 ></P
770 ><DIV
771 CLASS="VARIABLELIST"
772 ><DL
773 ><DT
774 ><TT
775 CLASS="FILENAME"
776 >/etc/nsswitch.conf(5)</TT
777 ></DT
778 ><DD
780 >Name service switch configuration file.</P
781 ></DD
782 ><DT
783 >/tmp/.winbindd/pipe</DT
784 ><DD
786 >The UNIX pipe over which clients communicate with
787 the <B
788 CLASS="COMMAND"
789 >winbindd</B
790 > program. For security reasons, the
791 winbind client will only attempt to connect to the winbindd daemon
792 if both the <TT
793 CLASS="FILENAME"
794 >/tmp/.winbindd</TT
795 > directory
796 and <TT
797 CLASS="FILENAME"
798 >/tmp/.winbindd/pipe</TT
799 > file are owned by
800 root. </P
801 ></DD
802 ><DT
803 >/lib/libnss_winbind.so.X</DT
804 ><DD
806 >Implementation of name service switch library.
808 ></DD
809 ><DT
810 >$LOCKDIR/winbindd_idmap.tdb</DT
811 ><DD
813 >Storage for the Windows NT rid to UNIX user/group
814 id mapping. The lock directory is specified when Samba is initially
815 compiled using the <TT
816 CLASS="FILENAME"
817 >--with-lockdir</TT
818 > option.
819 This directory is by default <TT
820 CLASS="FILENAME"
821 >/usr/local/samba/var/locks
822 </TT
823 >. </P
824 ></DD
825 ><DT
826 >$LOCKDIR/winbindd_cache.tdb</DT
827 ><DD
829 >Storage for cached user and group information.
831 ></DD
832 ></DL
833 ></DIV
834 ></DIV
835 ><DIV
836 CLASS="REFSECT1"
838 NAME="AEN253"
839 ></A
840 ><H2
841 >VERSION</H2
843 >This man page is correct for version 2.2 of
844 the Samba suite. winbindd is however not available in
845 stable release of Samba as of yet.</P
846 ></DIV
847 ><DIV
848 CLASS="REFSECT1"
850 NAME="AEN256"
851 ></A
852 ><H2
853 >SEE ALSO</H2
855 ><TT
856 CLASS="FILENAME"
857 >nsswitch.conf(5)</TT
860 HREF="samba.7.html"
861 TARGET="_top"
862 >samba(7)</A
865 HREF="wbinfo.1.html"
866 TARGET="_top"
867 >wbinfo(1)</A
870 HREF="smb.conf.5.html"
871 TARGET="_top"
872 >smb.conf(5)</A
873 ></P
874 ></DIV
875 ><DIV
876 CLASS="REFSECT1"
878 NAME="AEN263"
879 ></A
880 ><H2
881 >AUTHOR</H2
883 >The original Samba software and related utilities
884 were created by Andrew Tridgell. Samba is now developed
885 by the Samba Team as an Open Source project similar
886 to the way the Linux kernel is developed.</P
889 CLASS="COMMAND"
890 >wbinfo</B
891 > and <B
892 CLASS="COMMAND"
893 >winbindd</B
895 were written by Tim Potter.</P
897 >The conversion to DocBook for Samba 2.2 was done
898 by Gerald Carter</P
899 ></DIV
900 ></BODY
901 ></HTML