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" "11 November 2001" "" ""
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 \fIpasswd(5)\fR file and used by
44 \fBgetpwent(3)\fR functions.
47 Group information traditionally stored in
48 the \fIgroup(5)\fR file and used by
49 \fBgetgrent(3)\fR functions.
51 For example, the following simple configuration in the
52 \fI/etc/nsswitch.conf\fR file can be used to initially
53 resolve user and group information from \fI/etc/passwd
54 \fRand \fI/etc/group\fR and then from the
69 Sets the debuglevel to an integer between
70 0 and 100. 0 is for no debugging and 100 is for reams and
71 reams. To submit a bug report to the Samba Team, use debug
72 level 100 (see BUGS.txt).
75 Tells \fBwinbindd\fR to not
76 become a daemon and detach from the current terminal. This
77 option is used by developers when interactive debugging
78 of \fBwinbindd\fR is required.
79 .SH "NAME AND ID RESOLUTION"
81 Users and groups on a Windows NT server are assigned
82 a relative id (rid) which is unique for the domain when the
83 user or group is created. To convert the Windows NT user or group
84 into a unix user or group, a mapping between rids and unix user
85 and group ids is required. This is one of the jobs that \fB winbindd\fR performs.
87 As winbindd users and groups are resolved from a server, user
88 and group ids are allocated from a specified range. This
89 is done on a first come, first served basis, although all existing
90 users and groups will be mapped as soon as a client performs a user
91 or group enumeration command. The allocated unix ids are stored
92 in a database file under the Samba lock directory and will be
95 WARNING: The rid to unix id database is the only location
96 where the user and group mappings are stored by winbindd. If this
97 file is deleted or corrupted, there is no way for winbindd to
98 determine which user and group ids correspond to Windows NT user
102 Configuration of the \fBwinbindd\fR daemon
103 is done through configuration parameters in the \fIsmb.conf(5)
104 \fRfile. All parameters should be specified in the
105 [global] section of smb.conf.
107 \fBwinbind separator\fR
108 The winbind separator option allows you
109 to specify how NT domain names and user names are combined
110 into unix user names when presented to users. By default,
111 \fBwinbindd\fR will use the traditional '\\'
112 separator so that the unix user names look like
113 DOMAIN\\username. In some cases this separator character may
114 cause problems as the '\\' character has special meaning in
115 unix shells. In that case you can use the winbind separator
116 option to specify an alternative separator character. Good
117 alternatives may be '/' (although that conflicts
118 with the unix directory separator) or a '+ 'character.
119 The '+' character appears to be the best choice for 100%
120 compatibility with existing unix utilities, but may be an
121 aesthetically bad choice depending on your taste.
123 Default: \fBwinbind separator = \\ \fR
125 Example: \fBwinbind separator = + \fR
128 The winbind uid parameter specifies the
129 range of user ids that are allocated by the winbindd daemon.
130 This range of ids should have no existing local or NIS users
131 within it as strange conflicts can occur otherwise.
133 Default: \fBwinbind uid = <empty string>
135 Example: \fBwinbind uid = 10000-20000\fR
138 The winbind gid parameter specifies the
139 range of group ids that are allocated by the winbindd daemon.
140 This range of group ids should have no existing local or NIS
141 groups within it as strange conflicts can occur otherwise.
143 Default: \fBwinbind gid = <empty string>
145 Example: \fBwinbind gid = 10000-20000
147 \fBwinbind cache time\fR
148 This parameter specifies the number of
149 seconds the winbindd daemon will cache user and group information
150 before querying a Windows NT server again. When a item in the
151 cache is older than this time winbindd will ask the domain
152 controller for the sequence number of the server's account database.
153 If the sequence number has not changed then the cached item is
154 marked as valid for a further \fIwinbind cache time
155 \fRseconds. Otherwise the item is fetched from the
156 server. This means that as long as the account database is not
157 actively changing winbindd will only have to send one sequence
158 number query packet every \fIwinbind cache time
161 Default: \fBwinbind cache time = 15\fR
163 \fBwinbind enum users\fR
164 On large installations it may be necessary
165 to suppress the enumeration of users through the \fB setpwent()\fR, \fBgetpwent()\fR and
166 \fBendpwent()\fR group of system calls. If
167 the \fIwinbind enum users\fR parameter is false,
168 calls to the \fBgetpwent\fR system call will not
171 \fBWarning:\fR Turning off user enumeration
172 may cause some programs to behave oddly. For example, the \fBfinger\fR
173 program relies on having access to the full user list when
174 searching for matching usernames.
176 Default: \fBwinbind enum users = yes \fR
178 \fBwinbind enum groups\fR
179 On large installations it may be necessary
180 to suppress the enumeration of groups through the \fB setgrent()\fR, \fBgetgrent()\fR and
181 \fBendgrent()\fR group of system calls. If
182 the \fIwinbind enum groups\fR parameter is
183 false, calls to the \fBgetgrent()\fR system
184 call will not return any data.
186 \fBWarning:\fR Turning off group
187 enumeration may cause some programs to behave oddly.
189 Default: \fBwinbind enum groups = no \fR
191 \fBtemplate homedir\fR
192 When filling out the user information
193 for a Windows NT user, the \fBwinbindd\fR daemon
194 uses this parameter to fill in the home directory for that user.
195 If the string \fI%D\fR is present it is
196 substituted with the user's Windows NT domain name. If the
197 string \fI%U\fR is present it is substituted
198 with the user's Windows NT user name.
200 Default: \fBtemplate homedir = /home/%D/%U \fR
203 When filling out the user information for
204 a Windows NT user, the \fBwinbindd\fR daemon
205 uses this parameter to fill in the shell for that user.
207 Default: \fBtemplate shell = /bin/false \fR
210 To setup winbindd for user and group lookups plus
211 authentication from a domain controller use something like the
212 following setup. This was tested on a RedHat 6.2 Linux box.
214 In \fI/etc/nsswitch.conf\fR put the
219 passwd: files winbind
225 In \fI/etc/pam.d/*\fR replace the
226 \fIauth\fR lines with something like this:
230 auth required /lib/security/pam_securetty.so
231 auth required /lib/security/pam_nologin.so
232 auth sufficient /lib/security/pam_winbind.so
233 auth required /lib/security/pam_pwdb.so use_first_pass shadow nullok
238 Note in particular the use of the \fIsufficient\fR
239 keyword and the \fIuse_first_pass\fR keyword.
241 Now replace the account lines with this:
243 \fBaccount required /lib/security/pam_winbind.so
245 The next step is to join the domain. To do that use the
246 \fBsmbpasswd\fR program like this:
248 \fBsmbpasswd -j DOMAIN -r PDC -U
251 The username after the \fI-U\fR can be any
252 Domain user that has administrator privileges on the machine.
253 Substitute your domain name for "DOMAIN" and the name of your PDC
256 Next copy \fIlibnss_winbind.so\fR to
257 \fI/lib\fR and \fIpam_winbind.so\fR
258 to \fI/lib/security\fR. A symbolic link needs to be
259 made from \fI/lib/libnss_winbind.so\fR to
260 \fI/lib/libnss_winbind.so.2\fR. If you are using an
261 older version of glibc then the target of the link should be
262 \fI/lib/libnss_winbind.so.1\fR.
264 Finally, setup a \fIsmb.conf\fR containing directives like the
270 winbind separator = +
271 winbind cache time = 10
272 template shell = /bin/bash
273 template homedir = /home/%D/%U
274 winbind uid = 10000-20000
275 winbind gid = 10000-20000
283 Now start winbindd and you should find that your user and
284 group database is expanded to include your NT users and groups,
285 and that you can login to your unix box as a domain user, using
286 the DOMAIN+user syntax for the username. You may wish to use the
287 commands \fBgetent passwd\fR and \fBgetent group
288 \fRto confirm the correct operation of winbindd.
291 The following notes are useful when configuring and
292 running \fBwinbindd\fR:
294 \fBnmbd\fR must be running on the local machine
295 for \fBwinbindd\fR to work. \fBwinbindd\fR
296 queries the list of trusted domains for the Windows NT server
297 on startup and when a SIGHUP is received. Thus, for a running \fB winbindd\fR to become aware of new trust relationships between
298 servers, it must be sent a SIGHUP signal.
300 Client processes resolving names through the \fBwinbindd\fR
301 nsswitch module read an environment variable named \fB $WINBINDD_DOMAIN\fR. If this variable contains a comma separated
302 list of Windows NT domain names, then winbindd will only resolve users
303 and groups within those Windows NT domains.
305 PAM is really easy to misconfigure. Make sure you know what
306 you are doing when modifying PAM configuration files. It is possible
307 to set up PAM such that you can no longer log into your system.
309 If more than one UNIX machine is running \fBwinbindd\fR,
310 then in general the user and groups ids allocated by winbindd will not
311 be the same. The user and group ids will only be valid for the local
314 If the the Windows NT RID to UNIX user and group id mapping
315 file is damaged or destroyed then the mappings will be lost.
318 The following signals can be used to manipulate the
319 \fBwinbindd\fR daemon.
322 Reload the \fIsmb.conf(5)\fR
323 file and apply any parameter changes to the running
324 version of winbindd. This signal also clears any cached
325 user and group information. The list of other domains trusted
326 by winbindd is also reloaded.
329 The SIGUSR1 signal will cause \fB winbindd\fR to write status information to the winbind
330 log file including information about the number of user and
331 group ids allocated by \fBwinbindd\fR.
333 Log files are stored in the filename specified by the
337 \fB\fI/etc/nsswitch.conf(5)\fB\fR
338 Name service switch configuration file.
340 \fB/tmp/.winbindd/pipe\fR
341 The UNIX pipe over which clients communicate with
342 the \fBwinbindd\fR program. For security reasons, the
343 winbind client will only attempt to connect to the winbindd daemon
344 if both the \fI/tmp/.winbindd\fR directory
345 and \fI/tmp/.winbindd/pipe\fR file are owned by
348 \fB/lib/libnss_winbind.so.X\fR
349 Implementation of name service switch library.
351 \fB$LOCKDIR/winbindd_idmap.tdb\fR
352 Storage for the Windows NT rid to UNIX user/group
353 id mapping. The lock directory is specified when Samba is initially
354 compiled using the \fI--with-lockdir\fR option.
355 This directory is by default \fI/usr/local/samba/var/locks
358 \fB$LOCKDIR/winbindd_cache.tdb\fR
359 Storage for cached user and group information.
362 This man page is correct for version 2.2 of
366 \fInsswitch.conf(5)\fR,
372 The original Samba software and related utilities
373 were created by Andrew Tridgell. Samba is now developed
374 by the Samba Team as an Open Source project similar
375 to the way the Linux kernel is developed.
377 \fBwbinfo\fR and \fBwinbindd\fR
378 were written by Tim Potter.
380 The conversion to DocBook for Samba 2.2 was done