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" "24 April 2001" "" ""
8 winbindd \- Name Service Switch daemon for resolving names from NT servers
11 \fBnmblookup\fR [ \fB-d debuglevel\fR ] [ \fB-i\fR ] [ \fB-S\fR ] [ \fB-r\fR ] [ \fB-A\fR ] [ \fB-h\fR ] [ \fB-B <broadcast address>\fR ] [ \fB-U <unicast address>\fR ] [ \fB-d <debug level>\fR ] [ \fB-s <smb config file>\fR ] [ \fB-i <NetBIOS scope>\fR ] [ \fB-T\fR ] \fBname\fR
14 This tool is part of the Sambasuite version 3.0 and describes functionality not
15 yet implemented in the main version of Samba.
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 winbindd 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 following nsswitch databases are implemented by
36 User information traditionally stored in
37 the \fIpasswd(5)\fR file and used by
38 \fBgetpwent(3)\fR functions.
41 Group information traditionally stored in
42 the \fIgroup(5)\fR file and used by
43 \fBgetgrent(3)\fR functions.
45 For example, the following simple configuration in the
46 \fI/etc/nsswitch.conf\fR file can be used to initially
47 resolve user and group information from \fI/etc/passwd
48 \fRand \fI/etc/group\fR and then from the
63 Sets the debuglevel to an integer between
64 0 and 100. 0 is for no debugging and 100 is for reams and
65 reams. To submit a bug report to the Samba Team, use debug
66 level 100 (see BUGS.txt).
69 Tells \fBwinbindd\fR to not
70 become a daemon and detach from the current terminal. This
71 option is used by developers when interactive debugging
72 of \fBwinbindd\fR is required.
73 .SH "NAME AND ID RESOLUTION"
75 Users and groups on a Windows NT server are assigned
76 a relative id (rid) which is unique for the domain when the
77 user or group is created. To convert the Windows NT user or group
78 into a unix user or group, a mapping between rids and unix user
79 and group ids is required. This is one of the jobs that \fB winbindd\fR performs.
81 As winbindd users and groups are resolved from a server, user
82 and group ids are allocated from a specified range. This
83 is done on a first come, first served basis, although all existing
84 users and groups will be mapped as soon as a client performs a user
85 or group enumeration command. The allocated unix ids are stored
86 in a database file under the Samba lock directory and will be
89 WARNING: The rid to unix id database is the only location
90 where the user and group mappings are stored by winbindd. If this
91 file is deleted or corrupted, there is no way for winbindd to
92 determine which user and group ids correspond to Windows NT user
96 Configuration of the \fBwinbindd\fR daemon
97 is done through configuration parameters in the \fIsmb.conf(5)
98 \fRfile. All parameters should be specified in the
99 [global] section of smb.conf.
101 \fBwinbind separator\fR
102 The winbind separator option allows you
103 to specify how NT domain names and user names are combined
104 into unix user names when presented to users. By default,
105 \fBwinbindd\fR will use the traditional '\\'
106 separator so that the unix user names look like
107 DOMAIN\\username. In some cases this separator character may
108 cause problems as the '\\' character has special meaning in
109 unix shells. In that case you can use the winbind separator
110 option to specify an alternative sepataror character. Good
111 alternatives may be '/' (although that conflicts
112 with the unix directory separator) or a '+ 'character.
113 The '+' character appears to be the best choice for 100%
114 compatibility with existing unix utilities, but may be an
115 aesthetically bad choice depending on your taste.
117 Default: \fBwinbind separator = \\ \fR
119 Example: \fBwinbind separator = + \fR
122 The winbind uid parameter specifies the
123 range of user ids that are allocated by the winbindd daemon.
124 This range of ids should have no existing local or nis users
125 within it as strange conflicts can occur otherwise.
127 Default: \fBwinbind uid = <empty string>
129 Example: \fBwinbind uid = 10000-20000\fR
132 The winbind gid parameter specifies the
133 range of group ids that are allocated by the winbindd daemon.
134 This range of group ids should have no existing local or nis
135 groups within it as strange conflicts can occur otherwise.
137 Default: \fBwinbind gid = <empty string>
139 Example: \fBwinbind gid = 10000-20000
141 \fBwinbind cache time\fR
142 This parameter specifies the number of
143 seconds the winbindd daemon will cache user and group information
144 before querying a Windows NT server again. When a item in the
145 cache is older than this time winbindd will ask the domain
146 controller for the sequence number of the servers account database.
147 If the sequence number has not changed then the cached item is
148 marked as valid for a further \fIwinbind cache time
149 \fRseconds. Otherwise the item is fetched from the
150 server. This means that as long as the account database is not
151 actively changing winbindd will only have to send one sequence
152 number query packet every \fIwinbind cache time
155 Default: \fBwinbind cache time = 15\fR
157 \fBwinbind enum users\fR
158 On large installations it may be necessary
159 to suppress the enumeration of users through the \fB setpwent()\fR, \fBgetpwent()\fR and
160 \fBendpwent()\fR group of system calls. If
161 the \fIwinbind enum users\fR parameter is false,
162 calls to the \fBgetpwent\fR system call will not
165 \fBWarning:\fR Turning off user enumeration
166 may cause some programs to behave oddly. For example, the finger
167 program relies on having access to the full user list when
168 searching for matching usernames.
170 Default: \fBwinbind enum users = yes \fR
172 \fBwinbind enum groups\fR
173 On large installations it may be necessary
174 to suppress the enumeration of groups through the \fB setgrent()\fR, \fBgetgrent()\fR and
175 \fBendgrent()\fR group of system calls. If
176 the \fIwinbind enum groups\fR parameter is
177 false, calls to the \fBgetgrent()\fR system
178 call will not return any data.
180 \fBWarning:\fR Turning off group
181 enumeration may cause some programs to behave oddly.
183 Default: \fBwinbind enum groups = no \fR
185 \fBtemplate homedir\fR
186 When filling out the user information
187 for a Windows NT user, the \fBwinbindd\fR daemon
188 uses this parameter to fill in the home directory for that user.
189 If the string \fI%D\fR is present it is
190 substituted with the user's Windows NT domain name. If the
191 string \fI%U\fR is present it is substituted
192 with the user's Windows NT user name.
194 Default: \fBtemplate homedir = /home/%D/%U \fR
197 When filling out the user information for
198 a Windows NT user, the \fBwinbindd\fR daemon
199 uses this parameter to fill in the shell for that user.
201 Default: \fBtemplate shell = /bin/false \fR
204 To setup winbindd for user and group lookups plus
205 authentication from a domain controller use something like the
206 following setup. This was tested on a RedHat 6.2 Linux box.
208 In \fI/etc/nsswitch.conf\fR put the
213 passwd: files winbind
219 In \fI/etc/pam.d/*\fR replace the
220 \fIauth\fR lines with something like this:
224 auth required /lib/security/pam_securetty.so
225 auth required /lib/security/pam_nologin.so
226 auth sufficient /lib/security/pam_winbind.so
227 auth required /lib/security/pam_pwdb.so use_first_pass shadow nullok
232 Note in particular the use of the \fIsufficient\fR
233 keyword and the \fIuse_first_pass\fR keyword.
235 Now replace the account lines with this:
237 \fBaccount required /lib/security/pam_winbind.so
239 The next step is to join the domain. To do that use the
240 \fBsamedit\fR program like this:
242 \fBsamedit -S '*' -W DOMAIN -UAdministrator\fR
244 The username after the \fI-U\fR can be any Domain
245 user that has administrator priviliges on the machine. Next from
246 within \fBsamedit\fR, run the command:
248 \fBcreateuser MACHINE$ -j DOMAIN -L\fR
250 This assumes your domain is called "DOMAIN" and your Samba
251 workstation is called "MACHINE".
253 Next copy \fIlibnss_winbind.so.2\fR to
254 \fI/lib\fR and \fIpam_winbind.so\fR
255 to \fI/lib/security\fR.
257 Finally, setup a smb.conf containing directives like the
263 winbind separator = +
264 winbind cache time = 10
265 template shell = /bin/bash
266 template homedir = /home/%D/%U
267 winbind uid = 10000-20000
268 winbind gid = 10000-20000
276 Now start winbindd and you should find that your user and
277 group database is expanded to include your NT users and groups,
278 and that you can login to your unix box as a domain user, using
279 the DOMAIN+user syntax for the username. You may wish to use the
280 commands \fBgetent passwd\fR and \fBgetent group
281 \fRto confirm the correct operation of winbindd.
284 The following notes are useful when configuring and
285 running \fBwinbindd\fR:
287 \fBnmbd\fR must be running on the local machine
288 for \fBwinbindd\fR to work. \fBwinbindd\fR
289 queries the list of trusted domains for the Windows NT server
290 on startup and when a SIGHUP is received. Thus, for a running \fB winbindd\fR to become aware of new trust relationships between
291 servers, it must be sent a SIGHUP signal.
293 Client processes resolving names through the \fBwinbindd\fR
294 nsswitch module read an environment variable named \fI $WINBINDD_DOMAIN\fR. If this variable contains a comma separated
295 list of Windows NT domain names, then winbindd will only resolve users
296 and groups within those Windows NT domains.
298 PAM is really easy to misconfigure. Make sure you know what
299 you are doing when modifying PAM configuration files. It is possible
300 to set up PAM such that you can no longer log into your system.
302 If more than one UNIX machine is running \fBwinbindd\fR,
303 then in general the user and groups ids allocated by winbindd will not
304 be the same. The user and group ids will only be valid for the local
307 If the the Windows NT RID to UNIX user and group id mapping
308 file is damaged or destroyed then the mappings will be lost.
311 The following signals can be used to manipulate the
312 \fBwinbindd\fR daemon.
315 Reload the \fIsmb.conf(5)\fR
316 file and apply any parameter changes to the running
317 version of winbindd. This signal also clears any cached
318 user and group information. The list of other domains trusted
319 by winbindd is also reloaded.
322 The SIGUSR1 signal will cause \fB winbindd\fR to write status information to the winbind
323 log file including information about the number of user and
324 group ids allocated by \fBwinbindd\fR.
326 Log files are stored in the filename specified by the
330 \fB\fI/etc/nsswitch.conf(5)\fB\fR
331 Name service switch configuration file.
333 \fB/tmp/.winbindd/pipe\fR
334 The UNIX pipe over which clients communicate with
335 the \fBwinbindd\fR program. For security reasons, the
336 winbind client will only attempt to connect to the winbindd daemon
337 if both the \fI/tmp/.winbindd\fR directory
338 and \fI/tmp/.winbindd/pipe\fR file are owned by
341 \fB/lib/libnss_winbind.so.X\fR
342 Implementation of name service switch library.
344 \fB$LOCKDIR/winbindd_idmap.tdb\fR
345 Storage for the Windows NT rid to UNIX user/group
346 id mapping. The lock directory is specified when Samba is initially
347 compiled using the \fI--with-lockdir\fR option.
348 This directory is by default \fI/usr/local/samba/var/locks
351 \fB$LOCKDIR/winbindd_cache.tdb\fR
352 Storage for cached user and group information.
355 This man page is correct for version 2.2 of
356 the Samba suite. winbindd is however not available in
357 stable release of Samba as of yet.
360 \fInsswitch.conf(5)\fR,
363 smb.conf(5).SH "AUTHOR"
365 The original Samba software and related utilities
366 were created by Andrew Tridgell. Samba is now developed
367 by the Samba Team as an Open Source project similar
368 to the way the Linux kernel is developed.
370 \fBwbinfo\fR and \fBwinbindd\fR
371 were written by Tim Potter.
373 The conversion to DocBook for Samba 2.2 was done