1 .\" This manpage has been automatically generated by docbook2man
2 .\" from a DocBook document. This tool can be found at:
3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
4 .\" Please send any bug reports, improvements, comments, patches,
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "WINBINDD" "8" "04 March 2003" "" ""
8 winbindd \- Name Service Switch daemon for resolving names from NT servers
11 \fBwinbindd\fR [ \fB-F\fR ] [ \fB-S\fR ] [ \fB-i\fR ] [ \fB-B\fR ] [ \fB-d <debug level>\fR ] [ \fB-s <smb config file>\fR ] [ \fB-n\fR ]
15 This program is part of the Samba suite.
17 \fBwinbindd\fR is a daemon that provides
18 a service for the Name Service Switch capability that is present
19 in most modern C libraries. The Name Service Switch allows user
20 and system information to be obtained from different databases
21 services such as NIS or DNS. The exact behaviour can be configured
22 throught the \fI/etc/nsswitch.conf\fR file.
23 Users and groups are allocated as they are resolved to a range
24 of user and group ids specified by the administrator of the
27 The service provided by \fBwinbindd\fR is called `winbind' and
28 can be used to resolve user and group information from a
29 Windows NT server. The service can also provide authentication
30 services via an associated PAM module.
32 The \fIpam_winbind\fR module in the 2.2.2 release only
33 supports the \fIauth\fR and \fIaccount\fR
34 module-types. The latter simply
35 performs a getpwnam() to verify that the system can obtain a uid for the
36 user. If the \fIlibnss_winbind\fR library has been correctly
37 installed, this should always succeed.
39 The following nsswitch databases are implemented by
43 User information traditionally stored in
44 the \fIhosts(5)\fR file and used by
45 \fBgethostbyname(3)\fR functions. Names are
46 resolved through the WINS server or by broadcast.
49 User information traditionally stored in
50 the \fIpasswd(5)\fR file and used by
51 \fBgetpwent(3)\fR functions.
54 Group information traditionally stored in
55 the \fIgroup(5)\fR file and used by
56 \fBgetgrent(3)\fR functions.
58 For example, the following simple configuration in the
59 \fI/etc/nsswitch.conf\fR file can be used to initially
60 resolve user and group information from \fI/etc/passwd
61 \fR and \fI/etc/group\fR and then from the
71 The following simple configuration in the
72 \fI/etc/nsswitch.conf\fR file can be used to initially
73 resolve hostnames from \fI/etc/hosts\fR and then from the
78 If specified, this parameter causes
79 the main \fBwinbindd\fR process to not daemonize,
80 i.e. double-fork and disassociate with the terminal.
81 Child processes are still created as normal to service
82 each connection request, but the main process does not
83 exit. This operation mode is suitable for running
84 \fBwinbindd\fR under process supervisors such
85 as \fBsupervise\fR and \fBsvscan\fR
86 from Daniel J. Bernstein's \fBdaemontools\fR
87 package, or the AIX process monitor.
90 If specified, this parameter causes
91 \fBwinbindd\fR to log to standard output rather
95 Sets the debuglevel to an integer between
96 0 and 100. 0 is for no debugging and 100 is for reams and
97 reams. To submit a bug report to the Samba Team, use debug
98 level 100 (see BUGS.txt).
101 Tells \fBwinbindd\fR to not
102 become a daemon and detach from the current terminal. This
103 option is used by developers when interactive debugging
104 of \fBwinbindd\fR is required.
105 \fBwinbindd\fR also logs to standard output,
106 as if the \fB-S\fR parameter had been given.
109 Disable caching. This means winbindd will
110 always have to wait for a response from the domain controller
111 before it can respond to a client and this thus makes things
112 slower. The results will however be more accurate, since
113 results from the cache might not be up-to-date. This
114 might also temporarily hang winbindd if the DC doesn't respond.
117 Dual daemon mode. This means winbindd will run
118 as 2 threads. The first will answer all requests from the cache,
119 thus making responses to clients faster. The other will
120 update the cache for the query that the first has just responded.
121 Advantage of this is that responses are accurate and fast.
123 \fB-s|--conf=smb.conf\fR
124 Specifies the location of the all-important
126 .SH "NAME AND ID RESOLUTION"
128 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 \fB winbindd\fR performs.
134 As winbindd users and groups are resolved from a server, user
135 and group ids are allocated from a specified range. This
136 is done on a first come, first served basis, although all existing
137 users and groups will be mapped as soon as a client performs a user
138 or group enumeration command. The allocated unix ids are stored
139 in a database file under the Samba lock directory and will be
142 WARNING: The rid to unix id database is the only location
143 where the user and group mappings are stored by winbindd. If this
144 file is deleted or corrupted, there is no way for winbindd to
145 determine which user and group ids correspond to Windows NT user
149 Configuration of the \fBwinbindd\fR daemon
150 is done through configuration parameters in the \fIsmb.conf(5)
151 \fR file. All parameters should be specified in the
152 [global] section of smb.conf.
155 \fIwinbind separator\fR
164 \fIwinbind cache time\fR
167 \fIwinbind enum users\fR
170 \fIwinbind enum groups\fR
173 \fItemplate homedir\fR
179 \fIwinbind use default domain\fR
182 To setup winbindd for user and group lookups plus
183 authentication from a domain controller use something like the
184 following setup. This was tested on a RedHat 6.2 Linux box.
186 In \fI/etc/nsswitch.conf\fR put the
191 passwd: files winbind
196 In \fI/etc/pam.d/*\fR replace the
197 \fIauth\fR lines with something like this:
201 auth required /lib/security/pam_securetty.so
202 auth required /lib/security/pam_nologin.so
203 auth sufficient /lib/security/pam_winbind.so
204 auth required /lib/security/pam_pwdb.so use_first_pass shadow nullok
208 Note in particular the use of the \fIsufficient\fR
209 keyword and the \fIuse_first_pass\fR keyword.
211 Now replace the account lines with this:
213 \fBaccount required /lib/security/pam_winbind.so
216 The next step is to join the domain. To do that use the
217 \fBsmbpasswd\fR program like this:
219 \fBsmbpasswd -j DOMAIN -r PDC -U
222 The username after the \fI-U\fR can be any
223 Domain user that has administrator privileges on the machine.
224 Substitute your domain name for "DOMAIN" and the name of your PDC
227 Next copy \fIlibnss_winbind.so\fR to
228 \fI/lib\fR and \fIpam_winbind.so\fR
229 to \fI/lib/security\fR. A symbolic link needs to be
230 made from \fI/lib/libnss_winbind.so\fR to
231 \fI/lib/libnss_winbind.so.2\fR. If you are using an
232 older version of glibc then the target of the link should be
233 \fI/lib/libnss_winbind.so.1\fR.
235 Finally, setup a \fIsmb.conf\fR containing directives like the
241 winbind separator = +
242 winbind cache time = 10
243 template shell = /bin/bash
244 template homedir = /home/%D/%U
245 winbind uid = 10000-20000
246 winbind gid = 10000-20000
253 Now start winbindd and you should find that your user and
254 group database is expanded to include your NT users and groups,
255 and that you can login to your unix box as a domain user, using
256 the DOMAIN+user syntax for the username. You may wish to use the
257 commands \fBgetent passwd\fR and \fBgetent group
258 \fR to confirm the correct operation of winbindd.
261 The following notes are useful when configuring and
262 running \fBwinbindd\fR:
264 \fBnmbd\fR must be running on the local machine
265 for \fBwinbindd\fR to work. \fBwinbindd\fR
266 queries the list of trusted domains for the Windows NT server
267 on startup and when a SIGHUP is received. Thus, for a running \fB winbindd\fR to become aware of new trust relationships between
268 servers, it must be sent a SIGHUP signal.
270 Client processes resolving names through the \fBwinbindd\fR
271 nsswitch module read an environment variable named \fB $WINBINDD_DOMAIN\fR. If this variable contains a comma separated
272 list of Windows NT domain names, then winbindd will only resolve users
273 and groups within those Windows NT domains.
275 PAM is really easy to misconfigure. Make sure you know what
276 you are doing when modifying PAM configuration files. It is possible
277 to set up PAM such that you can no longer log into your system.
279 If more than one UNIX machine is running \fBwinbindd\fR,
280 then in general the user and groups ids allocated by winbindd will not
281 be the same. The user and group ids will only be valid for the local
284 If the the Windows NT RID to UNIX user and group id mapping
285 file is damaged or destroyed then the mappings will be lost.
288 The following signals can be used to manipulate the
289 \fBwinbindd\fR daemon.
292 Reload the \fIsmb.conf(5)\fR
293 file and apply any parameter changes to the running
294 version of winbindd. This signal also clears any cached
295 user and group information. The list of other domains trusted
296 by winbindd is also reloaded.
299 The SIGUSR1 signal will cause \fB winbindd\fR to write status information to the winbind
300 log file including information about the number of user and
301 group ids allocated by \fBwinbindd\fR.
303 Log files are stored in the filename specified by the
307 \fB\fI/etc/nsswitch.conf(5)\fB\fR
308 Name service switch configuration file.
310 \fB/tmp/.winbindd/pipe\fR
311 The UNIX pipe over which clients communicate with
312 the \fBwinbindd\fR program. For security reasons, the
313 winbind client will only attempt to connect to the winbindd daemon
314 if both the \fI/tmp/.winbindd\fR directory
315 and \fI/tmp/.winbindd/pipe\fR file are owned by
318 \fB/lib/libnss_winbind.so.X\fR
319 Implementation of name service switch library.
321 \fB$LOCKDIR/winbindd_idmap.tdb\fR
322 Storage for the Windows NT rid to UNIX user/group
323 id mapping. The lock directory is specified when Samba is initially
324 compiled using the \fI--with-lockdir\fR option.
325 This directory is by default \fI/usr/local/samba/var/locks
328 \fB$LOCKDIR/winbindd_cache.tdb\fR
329 Storage for cached user and group information.
332 This man page is correct for version 3.0 of
336 \fInsswitch.conf(5)\fR,
342 The original Samba software and related utilities
343 were created by Andrew Tridgell. Samba is now developed
344 by the Samba Team as an Open Source project similar
345 to the way the Linux kernel is developed.
347 \fBwbinfo\fR and \fBwinbindd\fR
348 were written by Tim Potter.
350 The conversion to DocBook for Samba 2.2 was done