The start of a long and ugly process... :-).

Jeremy.
(This used to be commit 9722a98f8f24ef528b02bfb42f53ef9d07e62aa1)

docs/manpages/smb.conf.5

@@ -1,4 +1,4 @@
-.TH SMB.CONF 5 "09 Oct 1998" "smb.conf 2.0.0-alpha11"
+.TH SMB.CONF 5 "13 Jun 1998" "smb.conf 1.9.18p8"
 .SH NAME
 smb.conf \- configuration file for smbd
 .SH SYNOPSIS
@@ -439,16 +439,22 @@ netbios aliases
 
 netbios name
 
+networkstation user login
+
 nis homedir
 
 null passwords
 
+ole locking compatibility
+
 os level
 
 packet size
 
 passwd chat
 
+passwd chat debug
+
 passwd program
 
 password level
@@ -511,8 +517,12 @@ time offset
 
 time server
 
+unix password sync
+
 unix realname
 
+update encrypted
+
 username level
 
 username map
@@ -638,8 +648,6 @@ max connections
 
 min print space
 
-networkstation user login
-
 only guest
 
 only user
@@ -672,6 +680,10 @@ printer name
 
 public
 
+queuepause command
+
+queueresume command
+
 read only
 
 read list
@@ -690,6 +702,8 @@ short preserve case
 
 strict locking
 
+strict sync
+
 sync always
 
 user
@@ -832,8 +846,22 @@ does what you expect.
 
 .SS alternate permissions (S)
 
-This option is deprecated and is only included for backward
-compatibility. 
+This option affects the way the "read only" DOS attribute is produced
+for UNIX files. If this is false then the read only bit is set for
+files on writeable shares which the user cannot write to.
+
+If this is true then it is set for files whos user write bit is not set.
+
+The latter behaviour is useful for when users copy files from each
+others directories, and use a file manager that preserves
+permissions. Without this option they may get annoyed as all copied
+files will have the "read only" bit set.
+
+.B Default:
+	alternate permissions = no
+
+.B Example:
+	alternate permissions = yes
 
 .SS available (S)
 This parameter lets you 'turn off' a service. If 'available = no', then
@@ -1254,8 +1282,9 @@ or you can live with the consequences of periodic pauses in nmbd service.
 
 .SS domain controller (G)
 
-A boolean that says whether Samba should be a domain controller or
-not. Set it to "yes" to be a domain controller.
+The meaning of this parameter changed from a string to a boolean (yes/no)
+value. It is currently not used within the Samba source and should be removed
+from all current smb.conf files. It is left behind for compatibility reasons.
 
 .B Default:
 	 domain controller = no
@@ -1671,7 +1700,14 @@ This is a list of users that should not be allowed to login to this
 service. This is really a "paranoid" check to absolutely ensure an
 improper setting does not breach your security.
 
-A name starting with @ is interpreted as a UNIX group.
+A name starting with @ is interpreted as a yp netgroup first (if this
+has been compiled into Samba), and then as a UNIX group if the name
+was not found in the yp netgroup database.
+
+A name starting with + is interpreted only by looking in the UNIX
+group database. A name starting with & is interpreted only by looking
+in the yp netgroup database (this has no effect if Samba is compiled
+without netgroup support).
 
 The current servicename is substituted for %S. This is useful in the
 [homes] section.
@@ -1690,8 +1726,13 @@ between 'keepalive' packets. If this parameter is zero, no keepalive packets
 will be sent. Keepalive packets, if sent, allow the server to tell whether a
 client is still present and responding.
 
+Keepalives should, in general, not be needed if the socket being used
+has the SO_KEEPALIVE attribute set on it (see "socket
+options"). Basically you should only use this option if you strike
+difficulties.
+
 .B Default:
- 	keep alive = 300
+ 	keep alive = 0
 
 .B Example:
  	keep alive = 60
@@ -1889,7 +1930,7 @@ This option takes the standard substitutions, allowing you to have
 separate logon scripts for each user or machine.
 
 .B Example:
-	logon script = scripts/%U.bat
+	logon script = scripts\\%U.bat
 
 .SS lppause command (S)
 This parameter specifies the command to be executed on the server host in
@@ -2485,11 +2526,17 @@ problems with machines in trust relationships in which case you can
 disable it here, but be warned, we have heard that some NT machines
 will then allow anyone in with any password! Make sure you test it.
 
+In Samba 1.9.18p5 this parameter is of limited use, as smbd now
+explicitly tests for this NT bug and will refuse to use a password
+server that has the problem. The parameter now defaults to off,
+and it should not be neccessary to set this parameter to on. It will
+be removed in a future Samba release.
+
 .B Default:
-	networkstation user login = yes
+	networkstation user login = no
 
 .B Example:
-	networkstation user login = no
+	networkstation user login = yes
 
 .SS null passwords (G)
 Allow or disallow access to accounts that have null passwords. 
@@ -2500,6 +2547,24 @@ Allow or disallow access to accounts that have null passwords.
 .B Example:
 	null passwords = yes
 
+.SS ole locking compatibility (G)
+
+This parameter allows an administrator to turn off the byte range
+lock manipulation that is done within Samba to give compatibility
+for OLE applications. Windows OLE applications use byte range locking
+as a form of inter-process communication, by locking ranges of bytes
+around the 2^32 region of a file range. This can cause certain UNIX
+lock managers to crash or otherwise cause problems. Setting this
+parameter to "no" means you trust your UNIX lock manager to handle
+such cases correctly.
+
+.B Default:
+     ole locking compatibility = yes
+
+.B Example:
+     ole locking compatibility = no
+
+
 .SS only guest (S)
 A synonym for this command is 'guest only'.
 
@@ -2575,6 +2640,14 @@ If the send string in any part of the chat sequence is a fullstop "."
 then no string is sent. Similarly, is the expect string is a fullstop
 then no string is expected.
 
+Note that if the 'unix password sync' parameter is set to true,
+then this sequence is called *AS ROOT* when the SMB password in the
+smbpasswd file is being changed, without access to the old password
+cleartext. In this case the old password cleartext is set to ""
+(the empty string).
+
+See also 'unix password sync' and 'passwd chat debug'
+
 .B Example:
         passwd chat = "*Enter OLD password*" %o\en "*Enter NEW password*" %n\en \e
                        "*Reenter NEW password*" %n\en "*Password changed*"
@@ -2583,18 +2656,44 @@ then no string is expected.
 .B Default:
        passwd chat = *old*password* %o\en *new*password* %n\en *new*password* %n\en *changed*
 
+.SS passwd chat debug (G)
+
+This boolean specifies if the passwd chat script parameter is run
+in 'debug' mode. In this mode the strings passed to and received
+from the passwd chat are printed in the smbd log with a debug level
+of 100. This is a dangerous option as it will allow plaintext passwords
+to be seen in the smbd log. It is available to help Samba admins
+debug their passwd chat scripts and should be turned off after
+this has been done. This parameter is off by default.
+
+.B Example:
+     passwd chat debug = True
+
+.B Default:
+     passwd chat debug = False
+
 .SS passwd program (G)
 The name of a program that can be used to set user passwords.
 
-This is only necessary if you have enabled remote password changing at
-compile time. Any occurrences of %u will be replaced with the user
-name.
+This is only available if you have enabled remote password changing at
+compile time (see the comments in the Makefile for details). Any occurrences 
+of %u will be replaced with the user name. The user name is checked
+for existance before calling the password changing program.
 
 Also note that many passwd programs insist in "reasonable" passwords,
 such as a minimum length, or the inclusion of mixed case chars and
 digits. This can pose a problem as some clients (such as Windows for
 Workgroups) uppercase the password before sending it. 
 
+Note that if the 'unix password sync' parameter is set to true,
+then this sequence is called *AS ROOT* when the SMB password in the
+smbpasswd file is being changed. If the 'unix passwd sync' parameter
+is set this parameter MUST USE ABSOLUTE PATHS for ALL programs called,
+and must be examined for security implications. Note that by default
+'unix password sync' is set to False.
+
+See also 'unix password sync'
+
 .B Default:
 	passwd program = /bin/passwd
 
@@ -3010,6 +3109,7 @@ phase in the SMB protocol takes care of choosing the appropriate protocol.
 
 .B Example:
 	protocol = LANMAN1
+
 .SS public (S)
 A synonym for this parameter is 'guest ok'.
 
@@ -3025,6 +3125,54 @@ this option.
 
 .B Example:
  	public = yes
+
+.SS queuepause command (S)
+This parameter specifies the command to be executed on the server host in
+order to pause the printerqueue.
+
+This command should be a program or script which takes a printer name
+as its only parameter and stops the printerqueue, such that no longer 
+jobs are submitted to the printer.
+
+This command is not supported by Windows for Workgroups, but can be
+issued from the Printer's window under Windows 95 & NT.
+
+If a %p is given then the printername is put in its place. Otherwise
+it is placed at the end of the command. 
+
+Note that it is good practice to include the absolute path in the 
+command as the PATH may not be available to the server.
+
+.B Default:
+        depends on the setting of "printing ="
+
+.B Example:
+      queuepause command = disable %p
+
+.SS queueresume command (S)
+This parameter specifies the command to be executed on the server host in
+order to resume the printerqueue. It is the command to undo the behaviour
+that is caused by the previous parameter (queuepause command).
+ 
+This command should be a program or script which takes a printer name
+as its only parameter and resumes the printerqueue, such that queued
+jobs are resubmitted to the printer.
+
+This command is not supported by Windows for Workgroups, but can be
+issued from the Printer's window under Windows 95 & NT.
+
+If a %p is given then the printername is put in its place. Otherwise
+it is placed at the end of the command.
+
+Note that it is good practice to include the absolute path in the 
+command as the PATH may not be available to the server.
+
+.B Default:
+        depends on the setting of "printing ="
+
+.B Example:
+      queuepause command = enable %p
+
 .SS read list (S)
 This is a list of users that are given read-only access to a
 service. If the connecting user is in this list then they will
@@ -3157,12 +3305,15 @@ master on it's segment.
 
 .SS revalidate (S)
 
-This options controls whether Samba will allow a previously validated
+This option controls whether Samba will allow a previously validated
 username/password pair to be used to attach to a share. Thus if you
 connect to \e\eserver\eshare1 then to \e\eserver\eshare2 it won't
 automatically allow the client to request connection to the second
 share as the same username as the first without a password.
 
+Note that this option only works with security=share and will
+be ignored if this is not the case.
+
 If "revalidate" is True then the client will be denied automatic
 access as the same username.
 
@@ -3239,7 +3390,11 @@ user that you are logged into WfWg as.
 
 If you use "security = server" then Samba will try to validate the
 username/password by passing it to another SMB server, such as an NT
-box. If this fails it will revert to "security = USER".
+box. If this fails it will revert to "security = USER", but note that
+if encrypted passwords have been negotiated then Samba cannot revert
+back to checking the UNIX password file, it must have a valid 
+smbpasswd file to check users against. See the documentation
+docs/ENCRYPTION.txt for details on how to set this up.
 
 See the "password server" option for more details.
 
@@ -3468,6 +3623,30 @@ so in the vast majority of cases "strict locking = no" is preferable.
 .B Example:
 	strict locking = yes
 
+.SS strict sync (S)
+Many Windows applications (including the Windows 98 explorer
+shell) seem to confuse flushing buffer contents to disk with
+doing a sync to disk. Under UNIX, a sync call forces the process
+to be suspended until the kernel has ensured that all outstanding
+data in kernel disk buffers has been safely stored onto stable
+storate. This is very slow and should only be done rarely. Setting
+this parameter to "no" (the default) means that smbd ignores the
+Windows applications requests for a sync call. There is only a
+possibility of losing data if the operating system itself that
+Samba is running on crashes, so there is little danger in this
+default setting. In addition, this fixes many performace problems
+that people have reported with the new Windows98 explorer shell
+file copies.
+
+See also the "sync always" parameter.
+
+.B Default:
+     strict sync = no
+
+.B Example:
+     strict sync = yes
+
+
 .SS strip dot (G)
 This is a boolean that controls whether to strip trailing dots off
 UNIX filenames. This helps with some CDROMs that have filenames ending in a
@@ -3507,6 +3686,10 @@ false then the server will be guided by the client's request in each
 write call (clients can set a bit indicating that a particular write
 should be synchronous). If this is true then every write will be
 followed by a fsync() call to ensure the data is written to disk.
+Note that the "strict sync" parameter must be set to "yes" in
+order for this parameter to have any affect.
+
+See also the "strict sync" parameter.
 
 .B Default:
 	sync always = no
@@ -3535,6 +3718,23 @@ to Windows clients. The default is False.
 .B Example:
 	time server = True
 
+.SS unix password sync (G)
+This boolean parameter controlls whether Samba attempts to synchronise
+the UNIX password with the SMB password when the encrypted SMB password
+in the smbpasswd file is changed. If this is set to true the 'passwd program'
+program is called *AS ROOT* - to allow the new UNIX password to be set
+without access to the old UNIX password (as the SMB password has change
+code has no access to the old password cleartext, only the new). By
+default this is set to false.
+
+See also 'passwd program', 'passwd chat'
+
+.B Default:
+         unix password sync = False
+
+.B Example:
+         unix password sync = True
+
 .SS unix realname (G)
 This boolean parameter when set causes samba to supply the real name field
 from the unix password file to the client. This is useful for setting up
@@ -3546,6 +3746,33 @@ mail clients and WWW browsers on systems used by more than one person.
 .B Example:
 	unix realname = yes
 
+.SS update encrypted (G)
+This boolean parameter allows a user logging on with a plaintext
+password to have their encrypted (hashed) password in the smbpasswd
+file to be updated automatically as they log on. This option allows
+a site to migrate from plaintext password authentication (users 
+authenticate with plaintext password over the wire, and are checked
+against a UNIX account database) to encrypted password authentication
+(the SMB challenge/response authentication mechanism) without forcing
+all users to re-enter their passwords via smbpasswd at the time the change
+is made. This is a convenience option to allow the change over to
+encrypted passwords to be made over a longer period. Once all users
+have encrypted representations of their passwords in the smbpasswd
+file this parameter should be set to "off".
+
+In order for this parameter to work correctly the "encrypt passwords"
+must be set to "no" when this parameter is set to "yes".
+
+Note that even when this parameter is set a user authenticating to
+smbd must still enter a valid password in order to connect correctly,
+and to update their hashed (smbpasswd) passwords.
+
+.B Default:
+	update encrypted = no
+
+.B Example:
+	update encrypted = yes
+
 .SS user (S)
 See
 .B username.
@@ -3579,8 +3806,19 @@ To restrict a service to a particular set of users you can use the
 "valid users=" line.
 
 If any of the usernames begin with a @ then the name will be looked up
-in the groups file and will expand to a list of all users in the group
-of that name. Note that searching though a groups file can take quite
+first in the yp netgroups list (if Samba is compiled with netgroup support),
+followed by a lookup in the UNIX groups database and will expand to a list of
+all users in the group of that name.
+
+If any of the usernames begin with a + then the name will be looked up only
+in the UNIX groups database and will expand to a list of all users in the 
+group of that name.
+
+If any of the usernames begin with a & then the name will be looked up only
+in the yp netgroups database (if Samba is compiled with netgroup support) and
+will expand to a list of all users in the netgroup group of that name.
+
+Note that searching though a groups database can take quite
 some time, and some clients may time out during the search.
 
 See the section below on username/password validation for more information
@@ -3627,7 +3865,7 @@ UNIX username on the left then a '=' followed by a list of usernames
 on the right. The list of usernames on the right may contain names of
 the form @group in which case they will match any UNIX username in
 that group. The special client name '*' is a wildcard and matches any
-name.
+name. Each line of the map file may be up to 1023 characters long.
 
 The file is processed on each line by taking the supplied username and
 comparing it with each username on the right hand side of the '='
@@ -3654,6 +3892,10 @@ would use
 
 You can have as many mappings as you like in a username map file.
 
+If Samba has been compiled with the -DNETGROUP compile option
+then the netgroup database is checked before the /etc/group
+database for matching groups.
+
 You can map Windows usernames that have spaces in them by using double
 quotes around the name. For example: