1 .\" This manpage has been automatically generated by docbook2man-spec
2 .\" from a DocBook document. docbook2man-spec can be found at:
3 .\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/>
4 .\" Please send any bug reports, improvements, comments, patches,
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "WINBINDD" "8" "08 May 2002" "" ""
8 winbindd \- Name Service Switch daemon for resolving names from NT servers
11 \fBwinbindd\fR [ \fB-i\fR ] [ \fB-d <debug level>\fR ] [ \fB-s <smb config file>\fR ]
14 This program is part of the Sambasuite.
16 \fBwinbindd\fR is a daemon that provides
17 a service for the Name Service Switch capability that is present
18 in most modern C libraries. The Name Service Switch allows user
19 and system information to be obtained from different databases
20 services such as NIS or DNS. The exact behaviour can be configured
21 throught the \fI/etc/nsswitch.conf\fR file.
22 Users and groups are allocated as they are resolved to a range
23 of user and group ids specified by the administrator of the
26 The service provided by \fBwinbindd\fR is called `winbind' and
27 can be used to resolve user and group information from a
28 Windows NT server. The service can also provide authentication
29 services via an associated PAM module.
31 The \fIpam_winbind\fR module in the 2.2.2 release only
32 supports the \fIauth\fR and \fIaccount\fR
33 module-types. The latter is simply
34 performs a getpwnam() to verify that the system can obtain a uid for the
35 user. If the \fIlibnss_winbind\fR library has been correctly
36 installed, this should always suceed.
38 The following nsswitch databases are implemented by
42 User information traditionally stored in
43 the \fIhosts(5)\fR file and used by
44 \fBgethostbyname(3)\fR functions. Names are
45 resolved through the WINS server or by broadcast.
48 User information traditionally stored in
49 the \fIpasswd(5)\fR file and used by
50 \fBgetpwent(3)\fR functions.
53 Group information traditionally stored in
54 the \fIgroup(5)\fR file and used by
55 \fBgetgrent(3)\fR functions.
57 For example, the following simple configuration in the
58 \fI/etc/nsswitch.conf\fR file can be used to initially
59 resolve user and group information from \fI/etc/passwd
60 \fRand \fI/etc/group\fR and then from the
73 The following simple configuration in the
74 \fI/etc/nsswitch.conf\fR file can be used to initially
75 resolve hostnames from \fI/etc/hosts\fR and then from the
81 Sets the debuglevel to an integer between
82 0 and 100. 0 is for no debugging and 100 is for reams and
83 reams. To submit a bug report to the Samba Team, use debug
84 level 100 (see BUGS.txt).
87 Tells \fBwinbindd\fR to not
88 become a daemon and detach from the current terminal. This
89 option is used by developers when interactive debugging
90 of \fBwinbindd\fR is required.
91 .SH "NAME AND ID RESOLUTION"
93 Users and groups on a Windows NT server are assigned
94 a relative id (rid) which is unique for the domain when the
95 user or group is created. To convert the Windows NT user or group
96 into a unix user or group, a mapping between rids and unix user
97 and group ids is required. This is one of the jobs that \fB winbindd\fR performs.
99 As winbindd users and groups are resolved from a server, user
100 and group ids are allocated from a specified range. This
101 is done on a first come, first served basis, although all existing
102 users and groups will be mapped as soon as a client performs a user
103 or group enumeration command. The allocated unix ids are stored
104 in a database file under the Samba lock directory and will be
107 WARNING: The rid to unix id database is the only location
108 where the user and group mappings are stored by winbindd. If this
109 file is deleted or corrupted, there is no way for winbindd to
110 determine which user and group ids correspond to Windows NT user
114 Configuration of the \fBwinbindd\fR daemon
115 is done through configuration parameters in the \fIsmb.conf(5)
116 \fRfile. All parameters should be specified in the
117 [global] section of smb.conf.
119 \fBwinbind separator\fR
120 The winbind separator option allows you
121 to specify how NT domain names and user names are combined
122 into unix user names when presented to users. By default,
123 \fBwinbindd\fR will use the traditional '\\'
124 separator so that the unix user names look like
125 DOMAIN\\username. In some cases this separator character may
126 cause problems as the '\\' character has special meaning in
127 unix shells. In that case you can use the winbind separator
128 option to specify an alternative separator character. Good
129 alternatives may be '/' (although that conflicts
130 with the unix directory separator) or a '+ 'character.
131 The '+' character appears to be the best choice for 100%
132 compatibility with existing unix utilities, but may be an
133 aesthetically bad choice depending on your taste.
135 Default: \fBwinbind separator = \\ \fR
137 Example: \fBwinbind separator = + \fR
140 The winbind uid parameter specifies the
141 range of user ids that are allocated by the winbindd daemon.
142 This range of ids should have no existing local or NIS users
143 within it as strange conflicts can occur otherwise.
145 Default: \fBwinbind uid = <empty string>
147 Example: \fBwinbind uid = 10000-20000\fR
150 The winbind gid parameter specifies the
151 range of group ids that are allocated by the winbindd daemon.
152 This range of group ids should have no existing local or NIS
153 groups within it as strange conflicts can occur otherwise.
155 Default: \fBwinbind gid = <empty string>
157 Example: \fBwinbind gid = 10000-20000
159 \fBwinbind cache time\fR
160 This parameter specifies the number of
161 seconds the winbindd daemon will cache user and group information
162 before querying a Windows NT server again. When a item in the
163 cache is older than this time winbindd will ask the domain
164 controller for the sequence number of the server's account database.
165 If the sequence number has not changed then the cached item is
166 marked as valid for a further \fIwinbind cache time
167 \fRseconds. Otherwise the item is fetched from the
168 server. This means that as long as the account database is not
169 actively changing winbindd will only have to send one sequence
170 number query packet every \fIwinbind cache time
173 Default: \fBwinbind cache time = 15\fR
175 \fBwinbind enum users\fR
176 On large installations it may be necessary
177 to suppress the enumeration of users through the \fB setpwent()\fR, \fBgetpwent()\fR and
178 \fBendpwent()\fR group of system calls. If
179 the \fIwinbind enum users\fR parameter is false,
180 calls to the \fBgetpwent\fR system call will not
183 \fBWarning:\fR Turning off user enumeration
184 may cause some programs to behave oddly. For example, the \fBfinger\fR
185 program relies on having access to the full user list when
186 searching for matching usernames.
188 Default: \fBwinbind enum users = yes \fR
190 \fBwinbind enum groups\fR
191 On large installations it may be necessary
192 to suppress the enumeration of groups through the \fB setgrent()\fR, \fBgetgrent()\fR and
193 \fBendgrent()\fR group of system calls. If
194 the \fIwinbind enum groups\fR parameter is
195 false, calls to the \fBgetgrent()\fR system
196 call will not return any data.
198 \fBWarning:\fR Turning off group
199 enumeration may cause some programs to behave oddly.
201 Default: \fBwinbind enum groups = no \fR
203 \fBtemplate homedir\fR
204 When filling out the user information
205 for a Windows NT user, the \fBwinbindd\fR daemon
206 uses this parameter to fill in the home directory for that user.
207 If the string \fI%D\fR is present it is
208 substituted with the user's Windows NT domain name. If the
209 string \fI%U\fR is present it is substituted
210 with the user's Windows NT user name.
212 Default: \fBtemplate homedir = /home/%D/%U \fR
215 When filling out the user information for
216 a Windows NT user, the \fBwinbindd\fR daemon
217 uses this parameter to fill in the shell for that user.
219 Default: \fBtemplate shell = /bin/false \fR
221 \fBwinbind use default domain\fR
222 This parameter specifies whether the \fBwinbindd\fR
223 daemon should operate on users without domain component in their username.
224 Users without a domain component are treated as is part of the winbindd server's
225 own domain. While this does not benifit Windows users, it makes SSH, FTP and e-mail
226 function in a way much closer to the way they would in a native unix system.
228 Default: \fBwinbind use default domain = <falseg>
230 Example: \fBwinbind use default domain = true\fR
233 To setup winbindd for user and group lookups plus
234 authentication from a domain controller use something like the
235 following setup. This was tested on a RedHat 6.2 Linux box.
237 In \fI/etc/nsswitch.conf\fR put the
242 passwd: files winbind
248 In \fI/etc/pam.d/*\fR replace the
249 \fIauth\fR lines with something like this:
253 auth required /lib/security/pam_securetty.so
254 auth required /lib/security/pam_nologin.so
255 auth sufficient /lib/security/pam_winbind.so
256 auth required /lib/security/pam_pwdb.so use_first_pass shadow nullok
261 Note in particular the use of the \fIsufficient\fR
262 keyword and the \fIuse_first_pass\fR keyword.
264 Now replace the account lines with this:
266 \fBaccount required /lib/security/pam_winbind.so
268 The next step is to join the domain. To do that use the
269 \fBsmbpasswd\fR program like this:
271 \fBsmbpasswd -j DOMAIN -r PDC -U
274 The username after the \fI-U\fR can be any
275 Domain user that has administrator privileges on the machine.
276 Substitute your domain name for "DOMAIN" and the name of your PDC
279 Next copy \fIlibnss_winbind.so\fR to
280 \fI/lib\fR and \fIpam_winbind.so\fR
281 to \fI/lib/security\fR. A symbolic link needs to be
282 made from \fI/lib/libnss_winbind.so\fR to
283 \fI/lib/libnss_winbind.so.2\fR. If you are using an
284 older version of glibc then the target of the link should be
285 \fI/lib/libnss_winbind.so.1\fR.
287 Finally, setup a \fIsmb.conf\fR containing directives like the
293 winbind separator = +
294 winbind cache time = 10
295 template shell = /bin/bash
296 template homedir = /home/%D/%U
297 winbind uid = 10000-20000
298 winbind gid = 10000-20000
306 Now start winbindd and you should find that your user and
307 group database is expanded to include your NT users and groups,
308 and that you can login to your unix box as a domain user, using
309 the DOMAIN+user syntax for the username. You may wish to use the
310 commands \fBgetent passwd\fR and \fBgetent group
311 \fRto confirm the correct operation of winbindd.
314 The following notes are useful when configuring and
315 running \fBwinbindd\fR:
317 \fBnmbd\fR must be running on the local machine
318 for \fBwinbindd\fR to work. \fBwinbindd\fR
319 queries the list of trusted domains for the Windows NT server
320 on startup and when a SIGHUP is received. Thus, for a running \fB winbindd\fR to become aware of new trust relationships between
321 servers, it must be sent a SIGHUP signal.
323 Client processes resolving names through the \fBwinbindd\fR
324 nsswitch module read an environment variable named \fB $WINBINDD_DOMAIN\fR. If this variable contains a comma separated
325 list of Windows NT domain names, then winbindd will only resolve users
326 and groups within those Windows NT domains.
328 PAM is really easy to misconfigure. Make sure you know what
329 you are doing when modifying PAM configuration files. It is possible
330 to set up PAM such that you can no longer log into your system.
332 If more than one UNIX machine is running \fBwinbindd\fR,
333 then in general the user and groups ids allocated by winbindd will not
334 be the same. The user and group ids will only be valid for the local
337 If the the Windows NT RID to UNIX user and group id mapping
338 file is damaged or destroyed then the mappings will be lost.
341 The following signals can be used to manipulate the
342 \fBwinbindd\fR daemon.
345 Reload the \fIsmb.conf(5)\fR
346 file and apply any parameter changes to the running
347 version of winbindd. This signal also clears any cached
348 user and group information. The list of other domains trusted
349 by winbindd is also reloaded.
352 The SIGUSR1 signal will cause \fB winbindd\fR to write status information to the winbind
353 log file including information about the number of user and
354 group ids allocated by \fBwinbindd\fR.
356 Log files are stored in the filename specified by the
360 \fB\fI/etc/nsswitch.conf(5)\fB\fR
361 Name service switch configuration file.
363 \fB/tmp/.winbindd/pipe\fR
364 The UNIX pipe over which clients communicate with
365 the \fBwinbindd\fR program. For security reasons, the
366 winbind client will only attempt to connect to the winbindd daemon
367 if both the \fI/tmp/.winbindd\fR directory
368 and \fI/tmp/.winbindd/pipe\fR file are owned by
371 \fB/lib/libnss_winbind.so.X\fR
372 Implementation of name service switch library.
374 \fB$LOCKDIR/winbindd_idmap.tdb\fR
375 Storage for the Windows NT rid to UNIX user/group
376 id mapping. The lock directory is specified when Samba is initially
377 compiled using the \fI--with-lockdir\fR option.
378 This directory is by default \fI/usr/local/samba/var/locks
381 \fB$LOCKDIR/winbindd_cache.tdb\fR
382 Storage for cached user and group information.
385 This man page is correct for version 2.2 of
389 \fInsswitch.conf(5)\fR,
395 The original Samba software and related utilities
396 were created by Andrew Tridgell. Samba is now developed
397 by the Samba Team as an Open Source project similar
398 to the way the Linux kernel is developed.
400 \fBwbinfo\fR and \fBwinbindd\fR
401 were written by Tim Potter.
403 The conversion to DocBook for Samba 2.2 was done