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" "18 February 2003" "" ""
   7
   8 .SH NAME
   9 winbindd \- Name Service Switch daemon for resolving names  from NT servers
  10 .SH SYNOPSIS
  11
  12 \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 ]
  13
  14 .SH "DESCRIPTION"
  15 .PP
  16 This program is part of the \fBSamba\fR(7) suite.
  17 .PP
  18 \fBwinbindd\fR is a daemon that provides
  19 a service for the Name Service Switch capability that is present
  20 in most modern C libraries.  The Name Service Switch allows user
  21 and system information to be obtained from different databases
  22 services such as NIS or DNS.  The exact behaviour can be configured
  23 throught the \fI/etc/nsswitch.conf\fR file.
  24 Users and groups are allocated as they are resolved to a range
  25 of user and group ids specified by the administrator of the
  26 Samba system.
  27 .PP
  28 The service provided by \fBwinbindd\fR is called `winbind' and
  29 can be used to resolve user and group information from a
  30 Windows NT server. The service can also provide authentication
  31 services via an associated PAM module.
  32 .PP
  33 The \fIpam_winbind\fR module in the 2.2.2 release only
  34 supports the \fIauth\fR and \fIaccount\fR
  35 module-types.  The latter simply
  36 performs a getpwnam() to verify that the system can obtain a uid for the
  37 user.  If the \fIlibnss_winbind\fR library has been correctly
  38 installed, this should always succeed.
  39 .PP
  40 The following nsswitch databases are implemented by
  41 the winbindd service:
  42 .TP
  43 \fBhosts\fR
  44 User information traditionally stored in
  45 the \fIhosts(5)\fR file and used by
  46 \fBgethostbyname(3)\fR functions. Names are
  47 resolved through the WINS server or by broadcast.
  48 .TP
  49 \fBpasswd\fR
  50 User information traditionally stored in
  51 the \fIpasswd(5)\fR file and used by
  52 \fBgetpwent(3)\fR functions.
  53 .TP
  54 \fBgroup\fR
  55 Group information traditionally stored in
  56 the \fIgroup(5)\fR file and used by
  57 \fBgetgrent(3)\fR functions.
  58 .PP
  59 For example, the following simple configuration in the
  60 \fI/etc/nsswitch.conf\fR file can be used to initially
  61 resolve user and group information from \fI/etc/passwd
  62 \fR and \fI/etc/group\fR and then from the
  63 Windows NT server.
  64
  65 .nf
  66 passwd:         files winbind
  67 group:          files winbind
  68 .fi
  69 .PP
  70 The following simple configuration in the
  71 \fI/etc/nsswitch.conf\fR file can be used to initially
  72 resolve hostnames from \fI/etc/hosts\fR and then from the
  73 WINS server.
  74 .SH "OPTIONS"
  75 .TP
  76 \fB-F\fR
  77 If specified, this parameter causes
  78 the main \fBwinbindd\fR process to not daemonize,
  79 i.e. double-fork and disassociate with the terminal.
  80 Child processes are still created as normal to service
  81 each connection request, but the main process does not
  82 exit. This operation mode is suitable for running
  83 \fBwinbindd\fR under process supervisors such
  84 as \fBsupervise\fR and \fBsvscan\fR
  85 from Daniel J. Bernstein's \fBdaemontools\fR
  86 package, or the AIX process monitor.
  87 .TP
  88 \fB-S\fR
  89 If specified, this parameter causes
  90 \fBwinbindd\fR to log to standard output rather
  91 than a file.
  92 .TP
  93 \fB-d debuglevel\fR
  94 Sets the debuglevel to an integer between
  95 0 and 100. 0 is for no debugging and 100 is for reams and
  96 reams. To submit a bug report to the Samba Team, use debug
  97 level 100 (see BUGS.txt).
  98 .TP
  99 \fB-i\fR
 100 Tells \fBwinbindd\fR to not
 101 become a daemon and detach from the current terminal. This
 102 option is used by developers when interactive debugging
 103 of \fBwinbindd\fR is required.
 104 \fBwinbindd\fR also logs to standard output,
 105 as if the \fB-S\fR parameter had been given.
 106 .TP
 107 \fB-n\fR
 108 Disable caching. This means winbindd will
 109 always have to wait for a response from the domain controller
 110 before it can respond to a client and this thus makes things
 111 slower. The results will however be more accurate, since
 112 results from the cache might not be up-to-date. This
 113 might also temporarily hang winbindd if the DC doesn't respond.
 114 .TP
 115 \fB-B\fR
 116 Dual daemon mode. This means winbindd will run
 117 as 2 threads. The first will answer all requests from the cache,
 118 thus making responses to clients faster. The other will
 119 update the cache for the query that the first has just responded.
 120 Advantage of this is that responses are accurate and fast.
 121 .TP
 122 \fB-s|--conf=smb.conf\fR
 123 Specifies the location of the all-important
 124 \fBsmb.conf\fR(5) file.
 125 .SH "NAME AND ID RESOLUTION"
 126 .PP
 127 Users and groups on a Windows NT server are assigned
 128 a relative id (rid) which is unique for the domain when the
 129 user or group is created.  To convert the Windows NT user or group
 130 into a unix user or group, a mapping between rids and unix user
 131 and group ids is required.  This is one of the jobs that \fB winbindd\fR performs.
 132 .PP
 133 As winbindd users and groups are resolved from a server, user
 134 and group ids are allocated from a specified range.  This
 135 is done on a first come, first served basis, although all existing
 136 users and groups will be mapped as soon as a client performs a user
 137 or group enumeration command.  The allocated unix ids are stored
 138 in a database file under the Samba lock directory and will be
 139 remembered.
 140 .PP
 141 WARNING: The rid to unix id database is the only location
 142 where the user and group mappings are stored by winbindd.  If this
 143 file is deleted or corrupted, there is no way for winbindd to
 144 determine which user and group ids correspond to Windows NT user
 145 and group rids.
 146 .SH "CONFIGURATION"
 147 .PP
 148 Configuration of the \fBwinbindd\fR daemon
 149 is done through configuration parameters in the \fBsmb.conf\fR(5) file.  All parameters should be specified in the
 150 [global] section of smb.conf.
 151 .TP 0.2i
 152 \(bu
 153 \fIwinbind separator\fR
 154 .TP 0.2i
 155 \(bu
 156 \fIwinbind uid\fR
 157 .TP 0.2i
 158 \(bu
 159 \fIwinbind gid\fR
 160 .TP 0.2i
 161 \(bu
 162 \fIwinbind cache time\fR
 163 .TP 0.2i
 164 \(bu
 165 \fIwinbind enum users\fR
 166 .TP 0.2i
 167 \(bu
 168 \fIwinbind enum groups\fR
 169 .TP 0.2i
 170 \(bu
 171 \fItemplate homedir\fR
 172 .TP 0.2i
 173 \(bu
 174 \fItemplate shell\fR
 175 .TP 0.2i
 176 \(bu
 177 \fIwinbind use default domain\fR
 178 .SH "EXAMPLE SETUP"
 179 .PP
 180 To setup winbindd for user and group lookups plus
 181 authentication from a domain controller use something like the
 182 following setup. This was tested on a RedHat 6.2 Linux box.
 183 .PP
 184 In \fI/etc/nsswitch.conf\fR put the
 185 following:
 186
 187 .nf
 188 passwd:     files winbind
 189 group:      files winbind
 190 .fi
 191 .PP
 192 In \fI/etc/pam.d/*\fR replace the \fI auth\fR lines with something like this:
 193
 194 .nf
 195 auth       required     /lib/security/pam_securetty.so
 196 auth       required     /lib/security/pam_nologin.so
 197 auth       sufficient   /lib/security/pam_winbind.so
 198 auth       required     /lib/security/pam_pwdb.so use_first_pass shadow nullok
 199 .fi
 200 .PP
 201 Note in particular the use of the \fIsufficient
 202 \fR keyword and the \fIuse_first_pass\fR keyword.
 203 .PP
 204 Now replace the account lines with this:
 205 .PP
 206 \fBaccount    required /lib/security/pam_winbind.so
 207 \fR
 208 .PP
 209 The next step is to join the domain. To do that use the
 210 \fBsmbpasswd\fR program like this:
 211 .PP
 212 \fBnet join -S PDC -U Administrator\fR
 213 .PP
 214 The username after the \fI-U\fR can be any
 215 Domain user that has administrator privileges on the machine.
 216 Substitute the name or IP of your PDC for "PDC".
 217 .PP
 218 Next copy \fIlibnss_winbind.so\fR to
 219 \fI/lib\fR and \fIpam_winbind.so
 220 \fR to \fI/lib/security\fR.  A symbolic link needs to be
 221 made from \fI/lib/libnss_winbind.so\fR to
 222 \fI/lib/libnss_winbind.so.2\fR.  If you are using an
 223 older version of glibc then the target of the link should be
 224 \fI/lib/libnss_winbind.so.1\fR.
 225 .PP
 226 Finally, setup a \fBsmb.conf\fR(5) containing directives like the
 227 following:
 228
 229 .nf
 230 [global]
 231         winbind separator = +
 232         winbind cache time = 10
 233         template shell = /bin/bash
 234         template homedir = /home/%D/%U
 235         winbind uid = 10000-20000
 236         winbind gid = 10000-20000
 237         workgroup = DOMAIN
 238         security = domain
 239         password server = *
 240 .fi
 241 .PP
 242 Now start winbindd and you should find that your user and
 243 group database is expanded to include your NT users and groups,
 244 and that you can login to your unix box as a domain user, using
 245 the DOMAIN+user syntax for the username. You may wish to use the
 246 commands \fBgetent passwd\fR and \fBgetent group
 247 \fR to confirm the correct operation of winbindd.
 248 .SH "NOTES"
 249 .PP
 250 The following notes are useful when configuring and
 251 running \fBwinbindd\fR:
 252 .PP
 253 \fBnmbd\fR(8) must be running on the local machine
 254 for \fBwinbindd\fR to work. \fBwinbindd\fR queries
 255 the list of trusted domains for the Windows NT server
 256 on startup and when a SIGHUP is received.  Thus, for a running \fB winbindd\fR to become aware of new trust relationships between
 257 servers, it must be sent a SIGHUP signal.
 258 .PP
 259 Client processes resolving names through the \fBwinbindd\fR
 260 nsswitch module read an environment variable named \fB $WINBINDD_DOMAIN\fR.  If this variable contains a comma separated
 261 list of Windows NT domain names, then winbindd will only resolve users
 262 and groups within those Windows NT domains.
 263 .PP
 264 PAM is really easy to misconfigure.  Make sure you know what
 265 you are doing when modifying PAM configuration files.  It is possible
 266 to set up PAM such that you can no longer log into your system.
 267 .PP
 268 If more than one UNIX machine is running \fBwinbindd\fR,
 269 then in general the user and groups ids allocated by winbindd will not
 270 be the same.  The user and group ids will only be valid for the local
 271 machine.
 272 .PP
 273 If the the Windows NT RID to UNIX user and group id mapping
 274 file is damaged or destroyed then the mappings will be lost.
 275 .SH "SIGNALS"
 276 .PP
 277 The following signals can be used to manipulate the
 278 \fBwinbindd\fR daemon.
 279 .TP
 280 \fBSIGHUP\fR
 281 Reload the \fBsmb.conf\fR(5) file and
 282 apply any parameter changes to the running
 283 version of winbindd.  This signal also clears any cached
 284 user and group information.  The list of other domains trusted
 285 by winbindd is also reloaded.
 286 .TP
 287 \fBSIGUSR1\fR
 288 The SIGUSR1 signal will cause \fB  winbindd\fR to write status information to the winbind
 289 log file including information about the number of user and
 290 group ids allocated by \fBwinbindd\fR.
 291
 292 Log files are stored in the filename specified by the
 293 log file parameter.
 294 .SH "FILES"
 295 .TP
 296 \fB\fI/etc/nsswitch.conf(5)\fB\fR
 297 Name service switch configuration file.
 298 .TP
 299 \fB/tmp/.winbindd/pipe\fR
 300 The UNIX pipe over which clients communicate with
 301 the \fBwinbindd\fR program.  For security reasons, the
 302 winbind client will only attempt to connect to the winbindd daemon
 303 if both the \fI/tmp/.winbindd\fR directory
 304 and \fI/tmp/.winbindd/pipe\fR file are owned by
 305 root.
 306 .TP
 307 \fB/lib/libnss_winbind.so.X\fR
 308 Implementation of name service switch library.
 309 .TP
 310 \fB$LOCKDIR/winbindd_idmap.tdb\fR
 311 Storage for the Windows NT rid to UNIX user/group
 312 id mapping.  The lock directory is specified when Samba is initially
 313 compiled using the \fI--with-lockdir\fR option.
 314 This directory is by default \fI/usr/local/samba/var/locks
 315 \fR.
 316 .TP
 317 \fB$LOCKDIR/winbindd_cache.tdb\fR
 318 Storage for cached user and group information.
 319 .SH "VERSION"
 320 .PP
 321 This man page is correct for version 3.0 of
 322 the Samba suite.
 323 .SH "SEE ALSO"
 324 .PP
 325 \fInsswitch.conf(5)\fR, \fBSamba\fR(7), \fBwbinfo\fR(8), \fBsmb.conf\fR(5)
 326 .SH "AUTHOR"
 327 .PP
 328 The original Samba software and related utilities
 329 were created by Andrew Tridgell. Samba is now developed
 330 by the Samba Team as an Open Source project similar
 331 to the way the Linux kernel is developed.
 332 .PP
 333 \fBwbinfo\fR and \fBwinbindd\fR were
 334 written by Tim Potter.
 335 .PP
 336 The conversion to DocBook for Samba 2.2 was done
 337 by Gerald Carter. The conversion to DocBook XML 4.2 for
 338 Samba 3.0 was done by Alexander Bokovoy.