update docs for "password server" and regenerate

also fixed a number of syntax errors in the SGML source
for several man pages (people really need to start validating
docs before checking them in).
(This used to be commit 91a21782e09562644ab4938cb0170b8fb94f0ccf)

1 files changed, 124 insertions, 87 deletions

diff --git a/docs/manpages/smb.conf.5 b/docs/manpages/smb.conf.5
index dc2adaba47..a9cf133c8d 100644
--- a/docs/manpages/smb.conf.5
+++ b/docs/manpages/smb.conf.5
@@ -3,7 +3,7 @@
 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
 .\" Please send any bug reports, improvements, comments, patches, 
 .\" etc. to Steve Cheng <steve@ggi-project.org>.
-.TH "SMB.CONF" "5" "03 October 2002" "" ""
+.TH "SMB.CONF" "5" "26 November 2002" "" ""
 .SH NAME
 smb.conf \- The configuration file for the Samba suite
 .SH "SYNOPSIS"
@@ -303,19 +303,6 @@ These substitutions are mostly noted in the descriptions below,
 but there are some general substitutions which apply whenever they 
 might be relevant. These are:
 .TP
-\fB%S\fR
-the name of the current service, if any.
-.TP
-\fB%P\fR
-the root directory of the current service, 
-if any.
-.TP
-\fB%u\fR
-user name of the current service, if any.
-.TP
-\fB%g\fR
-primary group name of %u.
-.TP
 \fB%U\fR
 session user name (the user name that the client 
 wanted, not necessarily the same as the one they got).
@@ -323,13 +310,6 @@ wanted, not necessarily the same as the one they got).
 \fB%G\fR
 primary group name of %U.
 .TP
-\fB%H\fR
-the home directory of the user given 
-by %u.
-.TP
-\fB%v\fR
-the Samba version.
-.TP
 \fB%h\fR
 the Internet hostname that Samba is running 
 on.
@@ -349,17 +329,6 @@ on port 445, as clients no longer send this information
 \fB%M\fR
 the Internet name of the client machine.
 .TP
-\fB%N\fR
-the name of your NIS home directory server.  
-This is obtained from your NIS auto.map entry.  If you have 
-not compiled Samba with the \fB--with-automount\fR 
-option then this value will be the same as %L.
-.TP
-\fB%p\fR
-the path of the service's home directory, 
-obtained from your NIS auto.map entry. The NIS auto.map entry 
-is split up as "%N:%p".
-.TP
 \fB%R\fR
 the selected protocol level after 
 protocol negotiation. It can be one of CORE, COREPLUS, 
@@ -384,10 +353,44 @@ The IP address of the client machine.
 \fB%T\fR
 the current date and time.
 .TP
+\fB%D\fR
+Name of the domain or workgroup of the current user.
+.TP
 \fB%$(\fIenvvar\fB)\fR
 The value of the environment variable
 \fIenvar\fR.
 .PP
+The following substitutes apply only to some configuration options(only those 
+that are used when a connection has been established):
+.TP
+\fB%S\fR
+the name of the current service, if any.
+.TP
+\fB%P\fR
+the root directory of the current service, 
+if any.
+.TP
+\fB%u\fR
+user name of the current service, if any.
+.TP
+\fB%g\fR
+primary group name of %u.
+.TP
+\fB%H\fR
+the home directory of the user given 
+by %u.
+.TP
+\fB%N\fR
+the name of your NIS home directory server.  
+This is obtained from your NIS auto.map entry.  If you have 
+not compiled Samba with the \fB--with-automount\fR 
+option then this value will be the same as %L.
+.TP
+\fB%p\fR
+the path of the service's home directory, 
+obtained from your NIS auto.map entry. The NIS auto.map entry 
+is split up as "%N:%p".
+.PP
 There are some quite creative things that can be done 
 with these substitutions and other smb.conf options.
 .SH "NAME MANGLING"
@@ -433,7 +436,7 @@ case. This option can be use with "preserve case = yes"
 to permit long filenames to retain their case, while short names 
 are lowercased. Default \fByes\fR.
 .PP
-By default, Samba 2.2 has the same semantics as a Windows 
+By default, Samba 3.0 has the same semantics as a Windows 
 NT server, in that it is case insensitive but case preserving.
 .SH "NOTE ABOUT USERNAME/PASSWORD VALIDATION"
 .PP
@@ -685,6 +688,9 @@ each parameter for details.  Note that some are synonyms.
 \fIldap passwd sync\fR
 .TP 0.2i
 \(bu
+\fIldap trust ids\fR
+.TP 0.2i
+\(bu
 \fIlm announce\fR
 .TP 0.2i
 \(bu
@@ -1713,10 +1719,10 @@ Example: \fBannounce as = Win95\fR
 \fBannounce version (G)\fR
 This specifies the major and minor version numbers 
 that nmbd will use when announcing itself as a server. The default 
-is 4.2.  Do not change this parameter unless you have a specific 
+is 4.9.  Do not change this parameter unless you have a specific 
 need to set a Samba server to be a downlevel server.
 
-Default: \fBannounce version = 4.5\fR
+Default: \fBannounce version = 4.9\fR
 
 Example: \fBannounce version = 2.0\fR
 .TP
@@ -1745,7 +1751,7 @@ Default: \fBavailable = yes\fR
 .TP
 \fBbind interfaces only (G)\fR
 This global parameter allows the Samba admin 
-to limit what interfaces on a machine will serve SMB requests. If 
+to limit what interfaces on a machine will serve SMB requests. It 
 affects file service smbd(8) and 
 name service nmbd(8) in slightly 
 different ways.
@@ -1764,7 +1770,7 @@ As unicast packets are received on the other sockets it allows
 \fBnmbd\fR to refuse to serve names to machines that 
 send packets that arrive through any interfaces not listed in the
 \fIinterfaces\fR list.  IP Source address spoofing
-does defeat this simple check, however so it must not be used
+does defeat this simple check, however, so it must not be used
 seriously as a security feature for \fBnmbd\fR.
 
 For file service it causes smbd(8)
@@ -1806,12 +1812,12 @@ to obtain a byte range lock on a region of an open file, and the
 request has a time limit associated with it.
 
 If this parameter is set and the lock range requested 
-cannot be immediately satisfied, Samba 2.2 will internally 
+cannot be immediately satisfied, samba will internally 
 queue the lock request, and periodically attempt to obtain 
 the lock until the timeout period expires.
 
 If this parameter is set to no, then 
-Samba 2.2 will behave as previous versions of Samba would and 
+samba will behave as previous versions of Samba would and 
 will fail the lock request immediately if the lock range 
 cannot be obtained.
 
@@ -2069,7 +2075,7 @@ effect.
 Default: \fBdebug pid = no\fR
 .TP
 \fBdebug timestamp (G)\fR
-Samba 2.2 debug log messages are timestamped 
+Samba debug log messages are timestamped 
 by default. If you are running at a high   \fIdebug level\fR these timestamps
 can be distracting. This boolean parameter allows timestamping 
 to be turned off.
@@ -2483,7 +2489,7 @@ Default: \fBdns proxy = yes\fR
 .TP
 \fBdomain logons (G)\fR
 If set to yes, the Samba server will serve 
-Windows 95/98 Domain logons for the   \fIworkgroup\fR it is in. Samba 2.2 also 
+Windows 95/98 Domain logons for the   \fIworkgroup\fR it is in. Samba 2.2
 has limited capability to act as a domain controller for Windows 
 NT 4 Domains.  For more details on setting up this feature see 
 the Samba-PDC-HOWTO included in the \fIhtmldocs/\fR
@@ -2933,7 +2939,7 @@ this by trying to log in as your guest user (perhaps by using the
 \fBsu -\fR command) and trying to print using the 
 system print command such as \fBlpr(1)\fR or \fB  lp(1)\fR.
 
-This paramater does not accept % macros, because
+This parameter does not accept % macros, because
 many parts of the system require this value to be
 constant for correct operation.
 
@@ -3391,20 +3397,25 @@ The \fIldap ssl\fR can be set to one of three values:
 .RS
 .TP 0.2i
 \(bu
-\fIOn\fR  =  Always use SSL when contacting the 
-\fIldap server\fR.
-.TP 0.2i
-\(bu
 \fIOff\fR = Never use SSL when querying the directory.
 .TP 0.2i
 \(bu
 \fIStart_tls\fR = Use the LDAPv3 StartTLS extended operation 
 (RFC2830) for communicating with the directory server.
+.TP 0.2i
+\(bu
+\fIOn\fR  =
+Use SSL on the ldaps port when contacting the 
+\fIldap server\fR.  Only
+available when the backwards-compatiblity \fB   --with-ldapsam\fR option is specified
+to configure.  See \fIpassdb backend\fR
 .RE
 
-Default : \fBldap ssl = on\fR
+Default : \fBldap ssl = start_tls\fR
 .TP
 \fBldap suffix (G)\fR
+Specifies where user and machine accounts are added to the tree. Can be overriden by \fBldap user suffix\fR and \fBldap machine suffix\fR. It also used as the base dn for all ldap searches. 
+
 Default : \fBnone\fR
 .TP
 \fBldap user suffix (G)\fR
@@ -3440,6 +3451,23 @@ The \fIldap passwd sync\fR can be set to one of three values:
 
 Default : \fBldap passwd sync = no\fR
 .TP
+\fBldap trust ids (G)\fR
+Normally, Samba validates each entry
+in the LDAP server against getpwnam().  This allows
+LDAP to be used for Samba with the unix system using
+NIS (for example) and also ensures that Samba does not
+present accounts that do not otherwise exist.  
+
+This option is used to disable this functionality, and
+instead to rely on the presence of the appropriate
+attributes in LDAP directly, which can result in a
+significant performance boost in some situations.  
+Setting this option to yes effectivly assumes
+that the local machine is running \fBnss_ldap\fR against the
+same LDAP server.
+
+Default: \fBldap trust ids = No\fR
+.TP
 \fBlevel2 oplocks (S)\fR
 This parameter controls whether Samba supports
 level2 (read-only) oplocks on a share.
@@ -3605,7 +3633,7 @@ Example: \fBlog file = /usr/local/samba/var/log.%m
 The value of the parameter (a astring) allows 
 the debug level (logging level) to be specified in the 
 \fIsmb.conf\fR file. This parameter has been
-extended since 2.2.x series, now it allow to specify the debug
+extended since the 2.2.x series, now it allow to specify the debug
 level for multiple debug classes. This is to give greater 
 flexibility in the configuration of the system.
 
@@ -4056,11 +4084,21 @@ a better algorithm (generates less collisions) in the names.
 However, many Win32 applications store the mangled names and so
 changing to the new algorithm must not be done
 lightly as these applications may break unless reinstalled.
-New installations of Samba may set the default to hash2.
 
-Default: \fBmangling method = hash\fR
+Default: \fBmangling method = hash2\fR
 
-Example: \fBmangling method = hash2\fR
+Example: \fBmangling method = hash\fR
+.TP
+\fBmangle prefix (G)\fR
+controls the number of prefix
+characters from the original name used when generating
+the mangled names. A larger value will give a weaker
+hash and therefore more name collisions. The minimum
+value is 1 and the maximum value is 6.
+
+Default: \fBmangle prefix = 1\fR
+
+Example: \fBmangle prefix = 4\fR
 .TP
 \fBmangled stack (G)\fR
 This parameter controls the number of mangled names 
@@ -4824,7 +4862,7 @@ Default: \fBparanoid server security = yes\fR
 \fBpassdb backend (G)\fR
 This option allows the administrator to chose which backends to retrieve and store passwords with. This allows (for example) both 
 smbpasswd and tdbsam to be used without a recompile. 
-Multiple backends can be specified, seperated by spaces. The backends will be searched in the order they are specified. New users are always added to the first backend specified.
+Multiple backends can be specified, separated by spaces. The backends will be searched in the order they are specified. New users are always added to the first backend specified.
 Experimental backends must still be selected
 (eg --with-tdbsam) at configure time.
 
@@ -4868,7 +4906,17 @@ backend.  Takes an LDAP URL as an optional argument (defaults to
 backend, with non unix account support.  Takes an LDAP URL as an optional argument (defaults to 
 \fBldap://localhost\fR)
 
-See also                         \fInon unix account range\fR
+Note:  In this module, any account without a matching POSIX account is regarded
+as 'non unix'.  
+
+See also                         \fInon unix account
+range\fR
+
+LDAP connections should be secured where
+possible.  This may be done using either
+Start-TLS (see                         \fIldap ssl\fR) or by
+specifying \fIldaps://\fR in
+the URL argument.  
 .TP 0.2i
 \(bu
 \fBnisplussam\fR - The NIS+ based passdb backend. Takes name NIS domain as an optional argument. Only works with sun NIS+ servers. 
@@ -5096,6 +5144,12 @@ doing a query for the name WORKGROUP<1C>
 and then contacting each server returned in the list of IP 
 addresses from the name resolution source. 
 
+If the list of servers contains both names and the '*'
+character, the list is treated as a list of preferred 
+domain controllers, but an auto lookup of all remaining DC's
+will be added to the list as well.  Samba will not attempt to optimize 
+this list by locating the closest DC.
+
 If the \fIsecurity\fR parameter is 
 set to server, then there are different
 restrictions that \fBsecurity = domain\fR doesn't 
@@ -5123,7 +5177,7 @@ See also the \fIsecurity
 
 Default: \fBpassword server = <empty string>\fR
 
-Example: \fBpassword server = NT-PDC, NT-BDC1, NT-BDC2
+Example: \fBpassword server = NT-PDC, NT-BDC1, NT-BDC2, *
 \fR
 
 Example: \fBpassword server = *\fR
@@ -5770,30 +5824,12 @@ Default: \fBremote browse sync = <empty string>
 \fR
 .TP
 \fBrestrict anonymous (G)\fR
-This is a boolean parameter.  If it is yes, then 
-anonymous access to the server will be restricted, namely in the 
-case where the server is expecting the client to send a username, 
-but it doesn't.  Setting it to yes will force these anonymous 
-connections to be denied, and the client will be required to always 
-supply a username and password when connecting. Use of this parameter 
-is only recommended for homogeneous NT client environments.
-
-This parameter makes the use of macro expansions that rely
-on the username (%U, %G, etc) consistent.  NT 4.0 
-likes to use anonymous connections when refreshing the share list, 
-and this is a way to work around that.
-
-When restrict anonymous is yes, all anonymous connections 
-are denied no matter what they are for.  This can effect the ability 
-of a machine to access the Samba Primary Domain Controller to revalidate 
-its machine account after someone else has logged on the client 
-interactively.  The NT client will display a message saying that 
-the machine's account in  the domain doesn't exist or the password is 
-bad.  The best way to deal  with this is to reboot NT client machines 
-between interactive logons,  using "Shutdown and Restart", rather 
-than "Close all programs and logon as a different user".
-
-Default: \fBrestrict anonymous = no\fR
+This is a integer parameter, and
+mirrors as much as possible the functinality the
+RestrictAnonymous
+registry key does on NT/Win2k.  
+
+Default: \fBrestrict anonymous = 0\fR
 .TP
 \fBroot (G)\fR
 Synonym for   \fIroot directory"\fR.
@@ -6553,7 +6589,8 @@ Example: \fBtotal print jobs = 5000\fR
 .TP
 \fBunicode (G)\fR
 Specifies whether Samba should try 
-to use unicode on the wire by default. 
+to use unicode on the wire by default. Note: This does NOT
+mean that samba will assume that the unix machine uses unicode!
 
 Default: \fBunicode = yes\fR
 .TP
@@ -6563,6 +6600,8 @@ Samba runs on uses. Samba needs to know this in order to be able to
 convert text to the charsets other SMB clients use.
 
 Default: \fBunix charset = ASCII\fR
+
+Example: \fBunix charset = UTF8\fR
 .TP
 \fBunix extensions(G)\fR
 This boolean parameter controls whether Samba 
@@ -6999,19 +7038,17 @@ Default: \fBvfs path = \fR
 Example: \fBvfs path = /usr/lib/samba/vfs\fR
 .TP
 \fBvfs object (S)\fR
-This parameter specifies a shared object file that 
-is used for Samba VFS I/O operations.  By default, normal 
+This parameter specifies a shared object files that 
+are used for Samba VFS I/O operations.  By default, normal 
 disk I/O operations are used but these can be overloaded 
-with a VFS object.  The Samba VFS layer is new to Samba 2.2 and 
-must be enabled at compile time with --with-vfs.
+with one or more VFS objects. 
 
 Default : \fBno value\fR
 .TP
 \fBvfs options (S)\fR
 This parameter allows parameters to be passed 
-to the vfs layer at initialization time.  The Samba VFS layer 
-is new to Samba 2.2 and must be enabled at compile time 
-with --with-vfs.  See also \fI  vfs object\fR.
+to the vfs layer at initialization time. 
+See also \fI  vfs object\fR.
 
 Default : \fBno value\fR
 .TP
@@ -7313,7 +7350,7 @@ sections. In particular, ensure that the permissions on spool
 directories are correct.
 .SH "VERSION"
 .PP
-This man page is correct for version 2.2 of 
+This man page is correct for version 3.0 of 
 the Samba suite.
 .SH "SEE ALSO"
 .PP