1WINBINDD(8)               System Administration tools              WINBINDD(8)
2
3
4

NAME

6       winbindd - Name Service Switch daemon for resolving names from NT
7       servers
8

SYNOPSIS

10       winbindd [-D|--daemon] [-i|--interactive] [-F|--foreground]
11        [--no-process-group] [-n|--no-caching] [-d <debug level>]
12        [--debug-stdout] [--configfile=<configuration file>]
13        [--option=<name>=<value>] [-l|--log-basename <log directory>]
14        [--leak-report] [--leak-report-full] [-V|--version]
15

DESCRIPTION

17       This program is part of the samba(7) suite.
18
19       winbindd is a daemon that provides a number of services to the Name
20       Service Switch capability found in most modern C libraries, to
21       arbitrary applications via PAM and ntlm_auth and to Samba itself.
22
23       Even if winbind is not used for nsswitch, it still provides a service
24       to smbd, ntlm_auth and the pam_winbind.so PAM module, by managing
25       connections to domain controllers. In this configuration the idmap
26       config * : range parameter is not required. (This is known as `netlogon
27       proxy only mode'.)
28
29       The Name Service Switch allows user and system information to be
30       obtained from different databases services such as NIS or DNS. The
31       exact behaviour can be configured through the /etc/nsswitch.conf file.
32       Users and groups are allocated as they are resolved to a range of user
33       and group ids specified by the administrator of the Samba system.
34
35       The service provided by winbindd is called `winbind' and can be used to
36       resolve user and group information from a Windows NT server. The
37       service can also provide authentication services via an associated PAM
38       module.
39
40       The pam_winbind module supports the auth, account and password
41       module-types. It should be noted that the account module simply
42       performs a getpwnam() to verify that the system can obtain a uid for
43       the user, as the domain controller has already performed access
44       control. If the libnss_winbind library has been correctly installed, or
45       an alternate source of names configured, this should always succeed.
46
47       The following nsswitch databases are implemented by the winbindd
48       service:
49
50       hosts
51           This feature is only available on IRIX. User information
52           traditionally stored in the hosts(5) file and used by
53           gethostbyname(3) functions. Names are resolved through the WINS
54           server or by broadcast.
55
56       passwd
57           User information traditionally stored in the passwd(5) file and
58           used by getpwent(3) functions.
59
60       group
61           Group information traditionally stored in the group(5) file and
62           used by getgrent(3) functions.
63
64       For example, the following simple configuration in the
65       /etc/nsswitch.conf file can be used to initially resolve user and group
66       information from /etc/passwd and /etc/group and then from the Windows
67       NT server.
68
69           passwd:         files winbind
70           group:          files winbind
71           ## only available on IRIX: use winbind to resolve hosts:
72           # hosts:        files dns winbind
73           ## All other NSS enabled systems should use libnss_wins.so like this:
74           hosts:          files dns wins
75
76
77       The following simple configuration in the /etc/nsswitch.conf file can
78       be used to initially resolve hostnames from /etc/hosts and then from
79       the WINS server.
80
81           hosts:         files wins
82

OPTIONS

84       -D|--daemon
85           If specified, this parameter causes the server to operate as a
86           daemon. That is, it detaches itself and runs in the background on
87           the appropriate port. This switch is assumed if winbindd is
88           executed on the command line of a shell.
89
90       -i|--interactive
91           Tells winbindd to not become a daemon and detach from the current
92           terminal. This option is used by developers when interactive
93           debugging of winbindd is required.  winbindd also logs to standard
94           output, as if the -S parameter had been given.
95
96       -F|--foreground
97           If specified, this parameter causes the main winbindd process to
98           not daemonize, i.e. double-fork and disassociate with the terminal.
99           Child processes are still created as normal to service each
100           connection request, but the main process does not exit. This
101           operation mode is suitable for running winbindd under process
102           supervisors such as supervise and svscan from Daniel J. Bernstein's
103           daemontools package, or the AIX process monitor.
104
105       --no-process-group
106           Do not create a new process group for winbindd.
107
108       -n|--no-caching
109           Disable some caching. This means winbindd will often have to wait
110           for a response from the domain controller before it can respond to
111           a client and this thus makes things slower. The results will
112           however be more accurate, since results from the cache might not be
113           up-to-date. This might also temporarily hang winbindd if the DC
114           doesn't respond. This does not disable the samlogon cache, which is
115           required for group membership tracking in trusted environments.
116
117       -d|--debuglevel=DEBUGLEVEL, --debug-stdout
118           level is an integer from 0 to 10. The default value if this
119           parameter is not specified is 0.
120
121           The higher this value, the more detail will be logged to the log
122           files about the activities of the server. At level 0, only critical
123           errors and serious warnings will be logged. Level 1 is a reasonable
124           level for day-to-day running - it generates a small amount of
125           information about operations carried out.
126
127           Levels above 1 will generate considerable amounts of log data, and
128           should only be used when investigating a problem. Levels above 3
129           are designed for use only by developers and generate HUGE amounts
130           of log data, most of which is extremely cryptic.
131
132           Note that specifying this parameter here will override the log
133           level parameter in the /etc/samba/smb.conf file.  This will
134           redirect debug output to STDOUT. By default server daemons are
135           logging to a log file.
136
137       --configfile=CONFIGFILE
138           The file specified contains the configuration details required by
139           the server. The information in this file includes server-specific
140           information such as what printcap file to use, as well as
141           descriptions of all the services that the server is to provide. See
142           /etc/samba/smb.conf for more information. The default configuration
143           file name is determined at compile time.
144
145       --option=<name>=<value>
146           Set the smb.conf(5) option "<name>" to value "<value>" from the
147           command line. This overrides compiled-in defaults and options read
148           from the configuration file. If a name or a value includes a space,
149           wrap whole --option=name=value into quotes.
150
151       -l|--log-basename=logdirectory
152           Base directory name for log/debug files. The parent process uses
153           filename log.winbindd, the child process uses filename
154           log.wb-<name>. The log file is never removed by winbindd.
155
156       --leak-report
157           Enable talloc leak reporting on exit.
158
159       --leak-report-full
160           Enable full talloc leak reporting on exit.
161
162       -V|--version
163           Prints the program version number.
164
165       -?|--help
166           Print a summary of command line options.
167
168       --usage
169           Display brief usage message.
170

NAME AND ID RESOLUTION

172       Users and groups on a Windows NT server are assigned a security id
173       (SID) which is globally unique when the user or group is created. To
174       convert the Windows NT user or group into a unix user or group, a
175       mapping between SIDs and unix user and group ids is required. This is
176       one of the jobs that winbindd performs.
177
178       As winbindd users and groups are resolved from a server, user and group
179       ids are allocated from a specified range. This is done on a first come,
180       first served basis, although all existing users and groups will be
181       mapped as soon as a client performs a user or group enumeration
182       command. The allocated unix ids are stored in a database and will be
183       remembered.
184
185       WARNING: The SID to unix id database is the only location where the
186       user and group mappings are stored by winbindd. If this store is
187       deleted or corrupted, there is no way for winbindd to determine which
188       user and group ids correspond to Windows NT user and group rids.
189

CONFIGURATION

191       Configuration of the winbindd daemon is done through configuration
192       parameters in the smb.conf(5) file. All parameters should be specified
193       in the [global] section of smb.conf.
194
195winbind separator
196
197idmap config * : range
198
199idmap config * : backend
200
201winbind cache time
202
203winbind enum users
204
205winbind enum groups
206
207template homedir
208
209template shell
210
211winbind use default domain
212
213winbind: rpc only Setting this parameter forces winbindd to
214                  use RPC instead of LDAP to retrieve information from Domain
215                  Controllers.
216

EXAMPLE SETUP

218       To setup winbindd for user and group lookups plus authentication from a
219       domain controller use something like the following setup. This was
220       tested on an early Red Hat Linux box.
221
222       In /etc/nsswitch.conf put the following:
223
224           passwd: files winbind
225           group:  files winbind
226
227       In /etc/pam.d/* replace the
228        auth lines with something like this:
229
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_unix.so \
234                             use_first_pass shadow nullok
235
236
237           Note
238           The PAM module pam_unix has recently replaced the module pam_pwdb.
239           Some Linux systems use the module pam_unix2 in place of pam_unix.
240
241       Note in particular the use of the sufficient keyword and the
242       use_first_pass keyword.
243
244       Now replace the account lines with this:
245
246       account required /lib/security/pam_winbind.so
247
248       The next step is to join the domain. To do that use the net program
249       like this:
250
251       net join -S PDC -U Administrator
252
253       The username after the -U can be any Domain user that has administrator
254       privileges on the machine. Substitute the name or IP of your PDC for
255       "PDC".
256
257       Next copy libnss_winbind.so to /lib and pam_winbind.so to
258       /lib/security. A symbolic link needs to be made from
259       /lib/libnss_winbind.so to /lib/libnss_winbind.so.2. If you are using an
260       older version of glibc then the target of the link should be
261       /lib/libnss_winbind.so.1.
262
263       Finally, setup a smb.conf(5) containing directives like the following:
264
265           [global]
266                winbind separator = +
267                   winbind cache time = 10
268                   template shell = /bin/bash
269                   template homedir = /home/%D/%U
270                   idmap config * : range = 10000-20000
271                   workgroup = DOMAIN
272                   security = domain
273                   password server = *
274
275       Now start winbindd and you should find that your user and group
276       database is expanded to include your NT users and groups, and that you
277       can login to your unix box as a domain user, using the DOMAIN+user
278       syntax for the username. You may wish to use the commands getent passwd
279       and getent group to confirm the correct operation of winbindd.
280

NOTES

282       The following notes are useful when configuring and running winbindd:
283
284       PAM is really easy to misconfigure. Make sure you know what you are
285       doing when modifying PAM configuration files. It is possible to set up
286       PAM such that you can no longer log into your system.
287
288       If more than one UNIX machine is running winbindd, then in general the
289       user and groups ids allocated by winbindd will not be the same. The
290       user and group ids will only be valid for the local machine, unless a
291       shared idmap config * : backend is configured.
292
293       If the Windows NT SID to UNIX user and group id mapping file is damaged
294       or destroyed then the mappings will be lost.
295

SIGNALS

297       The following signals can be used to manipulate the winbindd daemon.
298
299       SIGHUP
300           Reload the smb.conf(5) file and apply any parameter changes to the
301           running version of winbindd. This signal also clears any cached
302           user and group information. The list of other domains trusted by
303           winbindd is also reloaded.
304
305           Instead of sending a SIGHUP signal, a request to reload
306           configuration file may be sent using smbcontrol(1) program.
307
308       SIGUSR2
309           The SIGUSR2 signal will cause winbindd to write status information
310           to the winbind log file.
311
312           Log files are stored in the filename specified by the log file
313           parameter.
314

FILES

316       /etc/nsswitch.conf(5)
317           Name service switch configuration file.
318
319       /run/samba/winbindd/pipe
320           The UNIX pipe over which clients communicate with the winbindd
321           program. For security reasons, the winbind client will only attempt
322           to connect to the winbindd daemon if both the /run/samba/winbindd
323           directory and /run/samba/winbindd/pipe file are owned by root.
324
325           winbindd socket directory overrides this default.
326
327       $STATEDIR/winbindd_privileged/pipe
328           The UNIX pipe over which 'privileged' clients communicate with the
329           winbindd program. For security reasons, access to some winbindd
330           functions - like those needed by the ntlm_auth utility - is
331           restricted. By default, only users in the 'root' group will get
332           this access, however the administrator may change the group
333           permissions on $STATEDIR/winbindd_privileged to allow programs like
334           'squid' to use ntlm_auth. Note that the winbind client will only
335           attempt to connect to the winbindd daemon if both the
336           $STATEDIR/winbindd_privileged directory and
337           $STATEDIR/winbindd_privileged/pipe file are owned by root.
338
339           state dir controls what $STATEDIR refers to.
340
341       /lib/libnss_winbind.so.X
342           Implementation of name service switch library.
343
344       $STATEDIR/winbindd_idmap.tdb
345           Storage for the Windows NT rid to UNIX user/group id mapping. The
346           directory is specified when Samba is initially compiled using the
347           --with-statedir option or state dir. The default directory in this
348           installation is /var/lib/samba.
349
350       $LOCKDIR/winbindd_cache.tdb
351           Storage for cached user and group information.
352

VERSION

354       This man page is part of version 4.19.3 of the Samba suite.
355

SEE ALSO

357       nsswitch.conf(5), samba(7), wbinfo(1), ntlm_auth(8), smb.conf(5),
358       pam_winbind(8)
359

AUTHOR

361       The original Samba software and related utilities were created by
362       Andrew Tridgell. Samba is now developed by the Samba Team as an Open
363       Source project similar to the way the Linux kernel is developed.
364
365       wbinfo and winbindd were written by Tim Potter.
366
367       The conversion to DocBook for Samba 2.2 was done by Gerald Carter. The
368       conversion to DocBook XML 4.2 for Samba 3.0 was done by Alexander
369       Bokovoy.
370
371
372
373Samba 4.19.3                      11/27/2023                       WINBINDD(8)
Impressum