- added example config section to winbindd man page

- reran yodldocs with newer version of yodl
(This used to be commit faa3f49430775fd1bd327237f369f7b5df6fc0c6)

1 files changed, 108 insertions, 14 deletions

diff --git a/docs/yodldocs/winbindd.8.yo b/docs/yodldocs/winbindd.8.yo
index 77e14ad5f4..ce32565755 100644
--- a/docs/yodldocs/winbindd.8.yo
+++ b/docs/yodldocs/winbindd.8.yo
@@ -23,8 +23,10 @@ be configured throught the tt(/etc/nsswitch.conf) file.  Users and groups
 are allocated as they are resolved to a range of user and group ids
 specified by the administrator of the Samba system.  
 
-The service provided by bf(winbindd) is called `winbind' and can be used to
-resolve user and group information from a Windows NT server.  
+The service provided by bf(winbindd) is called `winbind' and can be
+used to resolve user and group information from a Windows NT server.
+The service can also provide authentication services via an associated
+PAM module.
 
 The following nsswitch databases are implemented by the bf(winbindd)
 service:
@@ -48,9 +50,10 @@ tt(/etc/nsswitch.conf) file can be used to initially resolve user and group
 information from tt(/etc/passwd) and tt(/etc/group) and then from the
 Windows NT server.
 
-tt(passwd:         files winbind)
-
-tt(group:          files winbind)
+verb(
+  passwd:         files winbind
+  group:          files winbind
+)
 
 label(OPTIONS)
 manpageoptions()
@@ -104,6 +107,23 @@ url(bf(smb.conf))(smb.conf.5.html).
 
 startdit()
 
+dit(winbind separator)
+
+The winbind separator option allows you to specify how NT domain names
+and user names are combined into unix user names when presented to
+users. By default winbind will use the traditional \ separator so
+that the unix user names look like DOMAIN\username. In some cases
+this separator character may cause problems as the \ character has
+special meaning in unix shells. In that case you can use the winbind
+separator option to specify an alternative sepataror character. Good
+alternatives may be / (although that conflicts with the unix directory
+separator) or a + character. The + character appears to be the best
+choice for 100% compatibility with existing unix utilities, but may be
+an aesthetically bad choice depending on your taste.
+
+  bf(Example:)
+tt(     winbind separator = +)
+
 dit(winbind uid)
 
 The winbind uid parameter specifies the range of user ids that are
@@ -134,10 +154,17 @@ dit(winbind cache time)
 
 This parameter specifies the number of seconds the
 url(bf(winbindd))(winbindd.8.html) daemon will cache user and group
-information before querying a Windows NT server again.
+information before querying a Windows NT server again. When a item in
+the cache is older than this time winbindd will ask the domain
+controller for the sequence number of the servers account database. If
+the sequence number has not changed then the cached item is marked as
+valid for a further "winbind cache time" seconds.  Otherwise the item
+is fetched from the server. This means that as long as the account
+database is not actively changing winbindd will only have to send one
+sequence number query packet every "winbind cache time" seconds.
 
   bf(Default:)
-tt(     winbind cache type = 15)
+tt(     winbind cache time = 15)
 
 dit(template homedir)
 
@@ -154,15 +181,83 @@ dit(template shell)
 
 When filling out the user information for a Windows NT user, the
 url(bf(winbindd))(winbindd.8.html) daemon uses this parameter to fill in
-the home directory for that user.  If the string tt(%D) is present it is
-substituted with the user's Windows NT domain name.  If the string tt(%U)
-is present it is substituted with the user's Windows NT user name.
+the shell for that user.  
 
   bf(Default:)
-tt(     template homedir = /home/%D/%U)
+tt(     template shell = /bin/false)
 
 enddit()
 
+
+label(EXAMPLESETUP)
+manpagesection(EXAMPLE SETUP)
+
+To setup winbindd for user and group lookups plus authentication from
+a domain controller use something like the following setup. This was
+tested on a RedHat 6.2 Linux box.
+
+In /etc/nsswitch.conf put the following:
+verb(
+   passwd:     files winbind
+   group:      files winbind
+)
+
+In /etc/pam.d/* replace the auth lines with something like this:
+verb(
+	auth       required	/lib/security/pam_securetty.so
+	auth       required	/lib/security/pam_nologin.so
+	auth       sufficient	/lib/security/pam_winbind.so
+	auth       required     /lib/security/pam_pwdb.so use_first_pass shadow nullok
+)
+
+Note in particular the use of the sufficient keyword and the
+use_first_pass keyword.
+
+Now replace the account lines with this:
+verb(
+	account    required	/lib/security/pam_winbind.so
+)
+
+The next step is to join the domain. To do that use the samedit
+program like this:
+verb(
+	samedit -S '*' -W DOMAIN -UAdministrator
+)
+
+Then within samedit run the command:
+verb(
+	createuser MACHINE$ -j DOMAIN -L
+)
+
+This assumes your domain is called DOMAIN and your Samba workstation
+is called MACHINE.
+
+Next copy libnss_winbind.so.2 to /lib and pam_winbind.so to
+/lib/security.
+
+Finally, setup a smb.conf containing directives like the following:
+verb(
+  [global]
+        winbind separator = +
+        winbind cache time = 10
+        template shell = /bin/bash
+        template homedir = /home/%D/%U
+        winbind uid = 10000-20000
+        winbind gid = 10000-20000
+        workgroup = DOMAIN
+        security = domain
+        password server = *
+)
+
+Now start winbindd and you should find that your user and group
+database is expanded to include your NT users and groups, and that you
+can login to your unix box as a domain user, using the DOMAIN+user
+syntax for the username. You may wish to use the commands "getent
+passwd" and "getent group" to confirm the correct operation of
+winbindd. 
+
+NOTE: nmbd must be running on the local machine for winbindd to work.
+
 label(FILES)
 manpagefiles()
 
@@ -211,8 +306,7 @@ label(AUTHOR)
 manpageauthor()
 
 The original Samba software and related utilities were created by
-Andrew Tridgell email(samba-bugs@samba.org). Samba is now developed
-by the Samba Team as an Open Source project similar to the way the
-Linux kernel is developed.
+Andrew Tridgell. Samba is now developed by the Samba Team as an Open
+Source project.
 
 Winbindd was written by Tim Potter.