- added example config section to winbindd man page

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

1 files changed, 113 insertions, 13 deletions

diff --git a/docs/htmldocs/winbindd.8.html b/docs/htmldocs/winbindd.8.html
index ad0edf32ac..1e6b822d34 100644
--- a/docs/htmldocs/winbindd.8.html
+++ b/docs/htmldocs/winbindd.8.html
@@ -36,8 +36,10 @@ different databases services such as NIS or DNS.  The exact behaviour can
 be configured throught the <code>/etc/nsswitch.conf</code> 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.  
-<p>The service provided by <strong>winbindd</strong> is called `winbind' and can be used to
-resolve user and group information from a Windows NT server.  
+<p>The service provided by <strong>winbindd</strong> 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.
 <p>The following nsswitch databases are implemented by the <strong>winbindd</strong>
 service:
 <p><dl>
@@ -52,8 +54,13 @@ service:
 <code>/etc/nsswitch.conf</code> file can be used to initially resolve user and group
 information from <code>/etc/passwd</code> and <code>/etc/group</code> and then from the
 Windows NT server.
-<p><code>passwd:         files winbind</code>
-<p><code>group:          files winbind</code>
+<p><pre>
+
+  passwd:         files winbind
+  group:          files winbind
+
+</pre>
+
 <p><a name="OPTIONS"></a>
 <h2>OPTIONS</h2>
     
@@ -96,6 +103,20 @@ parameters in the <a href="smb.conf.5.html"><strong>smb.conf</strong></a> file.
 should be specified in the [global] section of
 <a href="smb.conf.5.html"><strong>smb.conf</strong></a>.
 <p><dl>
+<p><p></p><dt><strong>winbind separator</strong><dd>
+<p>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.
+<p><strong>Example:</strong>
+<code>     winbind separator = +</code>
 <p><p></p><dt><strong>winbind uid</strong><dd>
 <p>The winbind uid parameter specifies the range of user ids that are
 allocated by the <a href="winbindd.8.html"><strong>winbindd</strong></a> daemon.  This range of
@@ -117,9 +138,16 @@ conflicts can occur otherwise.
 <p><p></p><dt><strong>winbind cache time</strong><dd>
 <p>This parameter specifies the number of seconds the
 <a href="winbindd.8.html"><strong>winbindd</strong></a> 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.
 <p><strong>Default:</strong>
-<code>     winbind cache type = 15</code>
+<code>     winbind cache time = 15</code>
 <p><p></p><dt><strong>template homedir</strong><dd>
 <p>When filling out the user information for a Windows NT user, the
 <a href="winbindd.8.html"><strong>winbindd</strong></a> daemon uses this parameter to fill in
@@ -131,12 +159,85 @@ is present it is substituted with the user's Windows NT user name.
 <p><p></p><dt><strong>template shell</strong><dd>
 <p>When filling out the user information for a Windows NT user, the
 <a href="winbindd.8.html"><strong>winbindd</strong></a> daemon uses this parameter to fill in
-the home directory for that user.  If the string <code>%D</code> is present it is
-substituted with the user's Windows NT domain name.  If the string <code>%U</code>
-is present it is substituted with the user's Windows NT user name.
+the shell for that user.  
 <p><strong>Default:</strong>
-<code>     template homedir = /home/%D/%U</code>
+<code>     template shell = /bin/false</code>
 <p></dl>
+<p><a name="EXAMPLESETUP"></a>
+<h2>EXAMPLE SETUP</h2>
+    
+<p>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.
+<p>In /etc/nsswitch.conf put the following:
+<pre>
+
+   passwd:     files winbind
+   group:      files winbind
+
+</pre>
+
+<p>In /etc/pam.d/* replace the auth lines with something like this:
+<pre>
+
+	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
+
+</pre>
+
+<p>Note in particular the use of the sufficient keyword and the
+use_first_pass keyword.
+<p>Now replace the account lines with this:
+<pre>
+
+	account    required	/lib/security/pam_winbind.so
+
+</pre>
+
+<p>The next step is to join the domain. To do that use the samedit
+program like this:
+<pre>
+
+	samedit -S '*' -W DOMAIN -UAdministrator
+
+</pre>
+
+<p>Then within samedit run the command:
+<pre>
+
+	createuser MACHINE$ -j DOMAIN -L
+
+</pre>
+
+<p>This assumes your domain is called DOMAIN and your Samba workstation
+is called MACHINE.
+<p>Next copy libnss_winbind.so.2 to /lib and pam_winbind.so to
+/lib/security.
+<p>Finally, setup a smb.conf containing directives like the following:
+<pre>
+
+  [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 = *
+
+</pre>
+
+<p>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. 
+<p>NOTE: nmbd must be running on the local machine for winbindd to work.
 <p><a name="FILES"></a>
 <h2>FILES</h2>
     
@@ -170,9 +271,8 @@ is damaged or destroyed then the mappings will be lost.
 <h2>AUTHOR</h2>
     
 <p>The original Samba software and related utilities were created by
-Andrew Tridgell <a href="mailto:samba-bugs@samba.org"><em>samba-bugs@samba.org</em></a>. 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.
 <p>Winbindd was written by Tim Potter.
 </body>
 </html>