docs/manpages/winbindd.8

   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" "" ""
   7 .SH NAME
   8 winbindd \- Name Service Switch daemon for resolving names  from NT servers
   9 .SH SYNOPSIS
  10
  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 ]
  12
  13 .SH "DESCRIPTION"
  14 .PP
  15 This program is part of the  Samba suite.
  16 .PP
  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
  25 Samba system.
  26 .PP
  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.
  31 .PP
  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.
  38 .PP
  39 The following nsswitch databases are implemented by
  40 the winbindd service:
  41 .TP
  42 \fBhosts\fR
  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.
  47 .TP
  48 \fBpasswd\fR
  49 User information traditionally stored in
  50 the \fIpasswd(5)\fR file and used by
  51 \fBgetpwent(3)\fR functions.
  52 .TP
  53 \fBgroup\fR
  54 Group information traditionally stored in
  55 the \fIgroup(5)\fR file and used by
  56 \fBgetgrent(3)\fR functions.
  57 .PP
  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
  62 Windows NT server.
  63 .PP
  64
  65 .nf
  66 passwd:         files winbind
  67 group:          files winbind
  68
  69 .fi
  70 .PP
  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
  74 WINS server.
  75 .SH "OPTIONS"
  76 .TP
  77 \fB-F\fR
  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.
  88 .TP
  89 \fB-S\fR
  90 If specified, this parameter causes
  91 \fBwinbindd\fR to log to standard output rather
  92 than a file.
  93 .TP
  94 \fB-d debuglevel\fR
  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).
  99 .TP
 100 \fB-i\fR
 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.
 107 .TP
 108 \fB-n\fR
 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.
 115 .TP
 116 \fB-B\fR
 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.
 122 .TP
 123 \fB-s|--conf=smb.conf\fR
 124 Specifies the location of the all-important
 125 \fIsmb.conf\fR file.
 126 .SH "NAME AND ID RESOLUTION"
 127 .PP
 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.
 133 .PP
 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
 140 remembered.
 141 .PP
 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
 146 and group rids.
 147 .SH "CONFIGURATION"
 148 .PP
 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.
 153 .TP 0.2i
 154 \(bu
 155 \fIwinbind separator\fR
 156 .TP 0.2i
 157 \(bu
 158 \fIwinbind uid\fR
 159 .TP 0.2i
 160 \(bu
 161 \fIwinbind gid\fR
 162 .TP 0.2i
 163 \(bu
 164 \fIwinbind cache time\fR
 165 .TP 0.2i
 166 \(bu
 167 \fIwinbind enum users\fR
 168 .TP 0.2i
 169 \(bu
 170 \fIwinbind enum groups\fR
 171 .TP 0.2i
 172 \(bu
 173 \fItemplate homedir\fR
 174 .TP 0.2i
 175 \(bu
 176 \fItemplate shell\fR
 177 .TP 0.2i
 178 \(bu
 179 \fIwinbind use default domain\fR
 180 .SH "EXAMPLE SETUP"
 181 .PP
 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.
 185 .PP
 186 In \fI/etc/nsswitch.conf\fR put the
 187 following:
 188 .PP
 189
 190 .nf
 191 passwd:     files winbind
 192 group:      files winbind
 193
 194 .fi
 195 .PP
 196 In \fI/etc/pam.d/*\fR replace the
 197 \fIauth\fR lines with something like this:
 198 .PP
 199
 200 .nf
 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
 205
 206 .fi
 207 .PP
 208 Note in particular the use of the \fIsufficient\fR
 209 keyword and the \fIuse_first_pass\fR keyword.
 210 .PP
 211 Now replace the account lines with this:
 212 .PP
 213 \fBaccount    required /lib/security/pam_winbind.so
 214 \fR
 215 .PP
 216 The next step is to join the domain. To do that use the
 217 \fBsmbpasswd\fR program like this:
 218 .PP
 219 \fBsmbpasswd -j DOMAIN -r PDC -U
 220 Administrator\fR
 221 .PP
 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
 225 for "PDC".
 226 .PP
 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.
 234 .PP
 235 Finally, setup a \fIsmb.conf\fR containing directives like the
 236 following:
 237 .PP
 238
 239 .nf
 240 [global]
 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
 247         workgroup = DOMAIN
 248         security = domain
 249         password server = *
 250
 251 .fi
 252 .PP
 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.
 259 .SH "NOTES"
 260 .PP
 261 The following notes are useful when configuring and
 262 running \fBwinbindd\fR:
 263 .PP
 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.
 269 .PP
 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.
 274 .PP
 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.
 278 .PP
 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
 282 machine.
 283 .PP
 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.
 286 .SH "SIGNALS"
 287 .PP
 288 The following signals can be used to manipulate the
 289 \fBwinbindd\fR daemon.
 290 .TP
 291 \fBSIGHUP\fR
 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.
 297 .TP
 298 \fBSIGUSR1\fR
 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.
 302
 303 Log files are stored in the filename specified by the
 304 log file parameter.
 305 .SH "FILES"
 306 .TP
 307 \fB\fI/etc/nsswitch.conf(5)\fB\fR
 308 Name service switch configuration file.
 309 .TP
 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
 316 root.
 317 .TP
 318 \fB/lib/libnss_winbind.so.X\fR
 319 Implementation of name service switch library.
 320 .TP
 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
 326 \fR.
 327 .TP
 328 \fB$LOCKDIR/winbindd_cache.tdb\fR
 329 Storage for cached user and group information.
 330 .SH "VERSION"
 331 .PP
 332 This man page is correct for version 3.0 of
 333 the Samba suite.
 334 .SH "SEE ALSO"
 335 .PP
 336 \fInsswitch.conf(5)\fR,
 337 samba(7)
 338 wbinfo(1)
 339 smb.conf(5)
 340 .SH "AUTHOR"
 341 .PP
 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.
 346 .PP
 347 \fBwbinfo\fR and \fBwinbindd\fR
 348 were written by Tim Potter.
 349 .PP
 350 The conversion to DocBook for Samba 2.2 was done
 351 by Gerald Carter