Add all the source files from the old CVS tree,

add the 5 missing chapters from the HOWTO
and add jht's Samba by Example book.
(This used to be commit 9fb5bcb93e57c5162b3ee6f9c7d777dc0269d100)

20 files changed, 461 insertions, 0 deletions

diff --git a/docs/smbdotconf/tuning/blocksize.xml b/docs/smbdotconf/tuning/blocksize.xml
new file mode 100644
index 0000000000..e6e5458163
--- /dev/null
+++ b/docs/smbdotconf/tuning/blocksize.xml
@@ -0,0 +1,23 @@
+<samba:parameter name="block size"
+				type="integer"
+                 context="S"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This parameter controls the behavior of <citerefentry><refentrytitle>smbd</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> when reporting disk free 
+    sizes. By default, this reports a disk block size of 1024 bytes.
+    </para>        
+		
+    <para>Changing this parameter may have some effect on the
+    efficiency of client writes, this is not yet confirmed. This
+    parameter was added to allow advanced administrators to change
+    it (usually to a higher value) and test the effect it has on
+    client write performance without re-compiling the code. As this
+    is an experimental option it may be removed in a future release.
+    </para>
+
+    <para>Changing this option does not change the disk free reporting
+    size, just the block size unit reported to the client.
+    </para>
+</description>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/changenotifytimeout.xml b/docs/smbdotconf/tuning/changenotifytimeout.xml
new file mode 100644
index 0000000000..16160f10af
--- /dev/null
+++ b/docs/smbdotconf/tuning/changenotifytimeout.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="change notify timeout"
+	type="integer"
+                 context="G"
+                 developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This SMB allows a client to tell a server to 
+    &quot;watch&quot; a particular directory for any changes and only reply to
+    the SMB request when a change has occurred. Such constant scanning of
+    a directory is expensive under UNIX, hence an <citerefentry><refentrytitle>smbd</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> daemon only performs such a scan 
+    on each requested directory once every <parameter moreinfo="none">change notify 
+    timeout</parameter> seconds.</para>
+</description>
+
+<value type="default">60</value>
+<value type="example">300<comment>Would change the scan time to every 5 minutes.</comment></value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/deadtime.xml b/docs/smbdotconf/tuning/deadtime.xml
new file mode 100644
index 0000000000..fd31043d36
--- /dev/null
+++ b/docs/smbdotconf/tuning/deadtime.xml
@@ -0,0 +1,28 @@
+<samba:parameter name="deadtime"
+                 context="G"
+                 developer="1"
+				 type="integer"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>The value of the parameter (a decimal integer) 
+    represents the number of minutes of inactivity before a connection 
+    is considered dead, and it is disconnected. The deadtime only takes 
+    effect if the number of open files is zero.</para>
+		
+    <para>This is useful to stop a server's resources being 
+    exhausted by a large number of inactive connections.</para>
+
+    <para>Most clients have an auto-reconnect feature when a 
+    connection is broken so in most cases this parameter should be 
+    transparent to users.</para>
+
+    <para>Using this parameter with a timeout of a few minutes 
+    is recommended for most systems.</para>
+
+    <para>A deadtime of zero indicates that no auto-disconnection 
+		should be performed.</para>
+</description>
+
+<value type="default">0</value>
+<value type="example">15</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/getwdcache.xml b/docs/smbdotconf/tuning/getwdcache.xml
new file mode 100644
index 0000000000..069f072db4
--- /dev/null
+++ b/docs/smbdotconf/tuning/getwdcache.xml
@@ -0,0 +1,14 @@
+<samba:parameter name="getwd cache"
+                 context="G"
+                 developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This is a tuning option. When this is enabled a 
+    caching algorithm will be used to reduce the time taken for getwd() 
+    calls. This can have a significant impact on performance, especially 
+    when the <link linkend="WIDELINKS"><parameter moreinfo="none">wide links</parameter>
+</link> parameter is set to <constant>no</constant>.</para>
+</description>
+
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/hostnamelookups.xml b/docs/smbdotconf/tuning/hostnamelookups.xml
new file mode 100644
index 0000000000..20fd98ce30
--- /dev/null
+++ b/docs/smbdotconf/tuning/hostnamelookups.xml
@@ -0,0 +1,16 @@
+<samba:parameter name="hostname lookups"
+                 context="G"
+				 type="boolean"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>Specifies whether samba should use (expensive)
+    hostname lookups or use the ip addresses instead. An example place
+    where hostname lookups are currently used is when checking 
+    the <command moreinfo="none">hosts deny</command> and <command moreinfo="none">hosts allow</command>.
+    </para>
+</description>
+
+<value type="default">yes</value>
+<value type="example">no</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/keepalive.xml b/docs/smbdotconf/tuning/keepalive.xml
new file mode 100644
index 0000000000..dd0c1ca51d
--- /dev/null
+++ b/docs/smbdotconf/tuning/keepalive.xml
@@ -0,0 +1,21 @@
+<samba:parameter name="keepalive"
+                 context="G"
+				 type="integer"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>The value of the parameter (an integer) represents 
+    the number of seconds between <parameter moreinfo="none">keepalive</parameter> 
+    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.</para>
+
+    <para>Keepalives should, in general, not be needed if the socket 
+    being used has the SO_KEEPALIVE attribute set on it (see <link linkend="SOCKETOPTIONS">
+    <parameter moreinfo="none">socket options</parameter></link>). 
+Basically you should only use this option if you strike difficulties.</para>
+</description>
+
+<value type="default">300</value>
+<value type="example">600</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/maxconnections.xml b/docs/smbdotconf/tuning/maxconnections.xml
new file mode 100644
index 0000000000..8636eb47dc
--- /dev/null
+++ b/docs/smbdotconf/tuning/maxconnections.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="max connections"
+                 context="S"
+				 type="integer"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This option allows the number of simultaneous connections to a service to be limited.
+    If <parameter moreinfo="none">max connections</parameter> is greater than 0 then connections
+    will be refused if this number of connections to the service are already open. A value 
+    of zero mean an unlimited number of connections may be made.</para>
+
+    <para>Record lock files are used to implement this feature. The lock files will be stored in 
+    the directory specified by the <link linkend="LOCKDIRECTORY">
+    <parameter moreinfo="none">lock directory</parameter></link> option.</para>
+</description>
+
+<value type="default">0</value>
+<value type="default">10</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/maxdisksize.xml b/docs/smbdotconf/tuning/maxdisksize.xml
new file mode 100644
index 0000000000..55de85a8d8
--- /dev/null
+++ b/docs/smbdotconf/tuning/maxdisksize.xml
@@ -0,0 +1,28 @@
+<samba:parameter name="max disk size"
+                 context="G"
+				 type="integer"
+                 developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This option allows you to put an upper limit 
+    on the apparent size of disks. If you set this option to 100 
+    then all shares will appear to be not larger than 100 MB in 
+    size.</para>
+
+    <para>Note that this option does not limit the amount of 
+    data you can put on the disk. In the above case you could still 
+    store much more than 100 MB on the disk, but if a client ever asks 
+    for the amount of free disk space or the total disk size then the 
+    result will be bounded by the amount specified in <parameter moreinfo="none">max 
+    disk size</parameter>.</para>
+
+    <para>This option is primarily useful to work around bugs 
+    in some pieces of software that can't handle very large disks, 
+    particularly disks over 1GB in size.</para>
+
+    <para>A <parameter moreinfo="none">max disk size</parameter> of 0 means no limit.</para>
+</description>
+
+<value type="default">0</value>
+<value type="example">1000</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/maxopenfiles.xml b/docs/smbdotconf/tuning/maxopenfiles.xml
new file mode 100644
index 0000000000..775fe064dd
--- /dev/null
+++ b/docs/smbdotconf/tuning/maxopenfiles.xml
@@ -0,0 +1,20 @@
+<samba:parameter name="max open files"
+				 type="integer"
+                 context="G"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This parameter limits the maximum number of 
+    open files that one <citerefentry><refentrytitle>smbd</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> file 
+    serving process may have open for a client at any one time. The 
+    default for this parameter is set very high (10,000) as Samba uses 
+    only one bit per unopened file.</para>
+		
+    <para>The limit of the number of open files is usually set 
+    by the UNIX per-process file descriptor limit rather than 
+    this parameter so you should never need to touch this parameter.</para>
+</description>
+
+<value type="default">10000</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/maxsmbdprocesses.xml b/docs/smbdotconf/tuning/maxsmbdprocesses.xml
new file mode 100644
index 0000000000..46e8222ca6
--- /dev/null
+++ b/docs/smbdotconf/tuning/maxsmbdprocesses.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="max smbd processes"
+				 type="integer"
+                 context="G"
+                 developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This parameter limits the maximum number of <citerefentry><refentrytitle>smbd</refentrytitle>                                       
+    <manvolnum>8</manvolnum></citerefentry> processes concurrently running on a system and is intended
+    as a stopgap to prevent degrading service to clients in the event that the server has insufficient
+    resources to handle more than this number of connections.  Remember that under normal operating
+    conditions, each user will have an <citerefentry><refentrytitle>smbd</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> associated with him or her to handle connections to all
+    shares from a given host.</para>
+</description>
+
+<value type="default">0</value>
+<value type="example">1000</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/minprintspace.xml b/docs/smbdotconf/tuning/minprintspace.xml
new file mode 100644
index 0000000000..cc5cac5621
--- /dev/null
+++ b/docs/smbdotconf/tuning/minprintspace.xml
@@ -0,0 +1,16 @@
+<samba:parameter name="min print space"
+                 context="S"
+				 type="integer"
+                 print="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This sets the minimum amount of free disk 
+    space that must be available before a user will be able to spool 
+    a print job. It is specified in kilobytes. The default is 0, which 
+    means a user can always spool a print job.</para>
+</description>
+
+<related>printing</related>
+<value type="default">0</value>
+<value type="example">2000</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/namecachetimeout.xml b/docs/smbdotconf/tuning/namecachetimeout.xml
new file mode 100644
index 0000000000..0d69d44809
--- /dev/null
+++ b/docs/smbdotconf/tuning/namecachetimeout.xml
@@ -0,0 +1,15 @@
+<samba:parameter name="name cache timeout"
+                 context="G"
+				 type="integer"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>Specifies the number of seconds it takes before 
+    entries in samba's hostname resolve cache time out. If 
+    the timeout is set to 0. the caching is disabled.
+</para>
+</description>
+
+<value type="default">660</value>
+<value type="example">0</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/paranoidserversecurity.xml b/docs/smbdotconf/tuning/paranoidserversecurity.xml
new file mode 100644
index 0000000000..44b53c268d
--- /dev/null
+++ b/docs/smbdotconf/tuning/paranoidserversecurity.xml
@@ -0,0 +1,19 @@
+<samba:parameter name="paranoid server security"
+                 context="G"
+				 type="boolean"
+                 developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>Some version of NT 4.x allow non-guest 
+    users with a bad passowrd. When this option is enabled, samba will not 
+    use a broken NT 4.x server as password server, but instead complain
+    to the logs and exit.  
+    </para>
+
+    <para>Disabling this option prevents Samba from making
+    this check, which involves deliberatly attempting a
+    bad logon to the remote server.</para>
+</description>
+
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/socketoptions.xml b/docs/smbdotconf/tuning/socketoptions.xml
new file mode 100644
index 0000000000..4d3dd37e07
--- /dev/null
+++ b/docs/smbdotconf/tuning/socketoptions.xml
@@ -0,0 +1,75 @@
+<samba:parameter name="socket options"
+                 context="G"
+				 type="list"
+                 developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This option allows you to set socket options 
+    to be used when talking with the client.</para>
+
+    <para>Socket options are controls on the networking layer 
+    of the operating systems which allow the connection to be 
+    tuned.</para>
+
+    <para>This option will typically be used to tune your Samba  server
+    for optimal performance for your local network. There is  no way
+    that Samba can know what the optimal parameters are for  your net,
+    so you must experiment and choose them yourself. We  strongly
+    suggest you read the appropriate documentation for your  operating
+    system first (perhaps <command moreinfo="none">man
+    setsockopt</command> will help).</para>
+
+    <para>You may find that on some systems Samba will say 
+    &quot;Unknown socket option&quot; when you supply an option. This means you 
+    either incorrectly  typed it or you need to add an include file 
+    to includes.h for your OS.  If the latter is the case please 
+    send the patch to <ulink url="mailto:samba-technical@samba.org">
+    samba-technical@samba.org</ulink>.</para>
+
+    <para>Any of the supported socket options may be combined 
+    in any way you like, as long as your OS allows it.</para>
+
+    <para>This is the list of socket options currently settable 
+    using this option:</para>
+
+    <itemizedlist>
+    	<listitem><para>SO_KEEPALIVE</para></listitem>
+    	<listitem><para>SO_REUSEADDR</para></listitem>
+    	<listitem><para>SO_BROADCAST</para></listitem>
+    	<listitem><para>TCP_NODELAY</para></listitem>
+    	<listitem><para>IPTOS_LOWDELAY</para></listitem>
+    	<listitem><para>IPTOS_THROUGHPUT</para></listitem>
+    	<listitem><para>SO_SNDBUF *</para></listitem>
+    	<listitem><para>SO_RCVBUF *</para></listitem>
+    	<listitem><para>SO_SNDLOWAT *</para></listitem>
+    	<listitem><para>SO_RCVLOWAT *</para></listitem>
+    </itemizedlist>
+
+    <para>Those marked with a <emphasis>'*'</emphasis> take an integer 
+    argument. The others can optionally take a 1 or 0 argument to enable 
+    or disable the option, by default they will be enabled if you 
+    don't specify 1 or 0.</para>
+
+    <para>To specify an argument use the syntax SOME_OPTION = VALUE 
+    for example <command moreinfo="none">SO_SNDBUF = 8192</command>. Note that you must 
+    not have any spaces before or after the = sign.</para>
+
+    <para>If you are on a local network then a sensible option 
+    might be:</para>
+
+    <para><command moreinfo="none">socket options = IPTOS_LOWDELAY</command></para>
+
+    <para>If you have a local network then you could try:</para>
+
+    <para><command moreinfo="none">socket options = IPTOS_LOWDELAY TCP_NODELAY</command></para>
+
+    <para>If you are on a wide area network then perhaps try 
+    setting IPTOS_THROUGHPUT. </para>
+
+    <para>Note that several of the options may cause your Samba 
+		server to fail completely. Use these options with caution!</para>
+</description>
+
+<value type="default">TCP_NODELAY</value>
+<value type="example">IPTOS_LOWDELAY</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/strictallocate.xml b/docs/smbdotconf/tuning/strictallocate.xml
new file mode 100644
index 0000000000..d1ffdf63a4
--- /dev/null
+++ b/docs/smbdotconf/tuning/strictallocate.xml
@@ -0,0 +1,24 @@
+<samba:parameter name="strict allocate"
+                 context="S"
+				 type="boolean"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This is a boolean that controls the handling of 
+    disk space allocation in the server. When this is set to <constant>yes</constant> 
+    the server will change from UNIX behaviour of not committing real
+    disk storage blocks when a file is extended to the Windows behaviour
+    of actually forcing the disk system to allocate real storage blocks
+    when a file is created or extended to be a given size. In UNIX
+    terminology this means that Samba will stop creating sparse files.
+    This can be slow on some systems.</para>
+
+    <para>When strict allocate is <constant>no</constant> the server does sparse
+    disk block allocation when a file is extended.</para>
+
+    <para>Setting this to <constant>yes</constant> can help Samba return
+    out of quota messages on systems that are restricting the disk quota
+    of users.</para>
+</description>
+
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/strictsync.xml b/docs/smbdotconf/tuning/strictsync.xml
new file mode 100644
index 0000000000..1d123cfe9c
--- /dev/null
+++ b/docs/smbdotconf/tuning/strictsync.xml
@@ -0,0 +1,24 @@
+<samba:parameter name="strict sync"
+                 context="S"
+				 type="boolean"
+                 xmlns:samba="http://samba.org/common">
+ <description>
+    <para>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 storage.
+    This is very slow and should only be done rarely. Setting this
+    parameter to <constant>no</constant> (the default) means that
+    <citerefentry><refentrytitle>smbd</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> 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 performance problems that people have
+    reported with the new Windows98 explorer shell file copies.</para>
+</description>
+
+<related>sync always</related>
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/syncalways.xml b/docs/smbdotconf/tuning/syncalways.xml
new file mode 100644
index 0000000000..1abe2b3e0e
--- /dev/null
+++ b/docs/smbdotconf/tuning/syncalways.xml
@@ -0,0 +1,21 @@
+<samba:parameter name="sync always"
+	context="S"
+	type="boolean"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This is a boolean parameter that controls 
+    whether writes will always be written to stable storage before 
+    the write call returns. If this is <constant>no</constant> 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 <constant>yes</constant> then every write will be followed by a <command moreinfo="none">fsync()
+    </command> call to ensure the data is written to disk. Note that 
+    the <parameter moreinfo="none">strict sync</parameter> parameter must be set to
+    <constant>yes</constant> in order for this parameter to have 
+    any affect.</para>
+</description>
+
+<related>strict sync</related>
+
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/usemmap.xml b/docs/smbdotconf/tuning/usemmap.xml
new file mode 100644
index 0000000000..e1f8ad71e2
--- /dev/null
+++ b/docs/smbdotconf/tuning/usemmap.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="use mmap"
+                 context="G"
+				 type="boolean"
+                 developer="1"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>This global parameter determines if the tdb internals of Samba can
+    depend on mmap working correctly on the running system. Samba requires a coherent
+    mmap/read-write system memory cache. Currently only HPUX does not have such a
+    coherent cache, and so this parameter is set to <constant>no</constant> by
+    default on HPUX. On all other systems this parameter should be left alone. This
+    parameter is provided to help the Samba developers track down problems with
+    the tdb internal code.
+    </para>
+</description>
+
+<value type="default">yes</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/usesendfile.xml b/docs/smbdotconf/tuning/usesendfile.xml
new file mode 100644
index 0000000000..e80598d463
--- /dev/null
+++ b/docs/smbdotconf/tuning/usesendfile.xml
@@ -0,0 +1,17 @@
+<samba:parameter name="use sendfile"
+                 context="S"
+				 type="boolean"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>If this parameter is <constant>yes</constant>, and Samba
+    was built with the --with-sendfile-support option, and the underlying operating
+    system supports sendfile system call, then some SMB read calls (mainly ReadAndX
+    and ReadRaw) will use the more efficient sendfile system call for files that
+    are exclusively oplocked. This may make more efficient use of the system CPU's
+    and cause Samba to be faster. This is off by default as it's effects are unknown
+    as yet. In particular, it appears that Windows 9X clients fail to work against
+    Samba with this parameter enabled in config.</para>
+</description>
+
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs/smbdotconf/tuning/writecachesize.xml b/docs/smbdotconf/tuning/writecachesize.xml
new file mode 100644
index 0000000000..85ebaa460a
--- /dev/null
+++ b/docs/smbdotconf/tuning/writecachesize.xml
@@ -0,0 +1,28 @@
+<samba:parameter name="write cache size"
+                 context="S"
+				 type="integer"
+                 xmlns:samba="http://samba.org/common">
+<description>
+    <para>If this integer parameter is set to non-zero value,
+    Samba will create an in-memory cache for each oplocked file 
+    (it does <emphasis>not</emphasis> do this for 
+    non-oplocked files). All writes that the client does not request 
+    to be flushed directly to disk will be stored in this cache if possible. 
+    The cache is flushed onto disk when a write comes in whose offset 
+    would not fit into the cache or when the file is closed by the client. 
+    Reads for the file are also served from this cache if the data is stored 
+    within it.</para>
+
+    <para>This cache allows Samba to batch client writes into a more 
+    efficient write size for RAID disks (i.e. writes may be tuned to 
+    be the RAID stripe size) and can improve performance on systems 
+    where the disk subsystem is a bottleneck but there is free 
+    memory for userspace programs.</para>
+
+    <para>The integer parameter specifies the size of this cache 
+		(per oplocked file) in bytes.</para>
+</description>
+
+<value type="default">0</value>
+<value type="example">262144<comment> for a 256k cache size per file</comment></value>
+</samba:parameter>