diff options
Diffstat (limited to 'docs/docbook/smbdotconf/tuning')
22 files changed, 455 insertions, 388 deletions
diff --git a/docs/docbook/smbdotconf/tuning/blocksize.xml b/docs/docbook/smbdotconf/tuning/blocksize.xml index da42ca9ece..eecf1925e8 100644 --- a/docs/docbook/smbdotconf/tuning/blocksize.xml +++ b/docs/docbook/smbdotconf/tuning/blocksize.xml @@ -1,19 +1,22 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="BLOCKSIZE"/>block size (S)</term> - <listitem><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> +<samba:parameter name="block size" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <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 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> - </listitem> - </samba:parameter> + <para>Changing this option does not change the disk free reporting + size, just the block size unit reported to the client. + </para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/changenotifytimeout.xml b/docs/docbook/smbdotconf/tuning/changenotifytimeout.xml index 18c8b9a176..471798c269 100644 --- a/docs/docbook/smbdotconf/tuning/changenotifytimeout.xml +++ b/docs/docbook/smbdotconf/tuning/changenotifytimeout.xml @@ -1,15 +1,20 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="CHANGENOTIFYTIMEOUT"/>change notify timeout (G)</term> - <listitem><para>This SMB allows a client to tell a server to - "watch" 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> +<samba:parameter name="change notify timeout" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This SMB allows a client to tell a server to + "watch" 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> - <para>Default: <command moreinfo="none">change notify timeout = 60</command></para> - <para>Example: <command moreinfo="none">change notify timeout = 300</command></para> + <para>Default: <command moreinfo="none">change notify timeout = 60</command></para> - <para>Would change the scan time to every 5 minutes.</para></listitem> - </samba:parameter> + <para>Example: <command moreinfo="none">change notify timeout = 300</command></para> + + <para>Would change the scan time to every 5 minutes.</para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/deadtime.xml b/docs/docbook/smbdotconf/tuning/deadtime.xml index dbad06f25b..cbbf751862 100644 --- a/docs/docbook/smbdotconf/tuning/deadtime.xml +++ b/docs/docbook/smbdotconf/tuning/deadtime.xml @@ -1,23 +1,27 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="DEADTIME"/>deadtime (G)</term> - <listitem><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> +<samba:parameter name="dead time" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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>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>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>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> + <para>A deadtime of zero indicates that no auto-disconnection + should be performed.</para> - <para>Default: <command moreinfo="none">deadtime = 0</command></para> - <para>Example: <command moreinfo="none">deadtime = 15</command></para></listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">deadtime = 0</command></para> + <para>Example: <command moreinfo="none">deadtime = 15</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/getwdcache.xml b/docs/docbook/smbdotconf/tuning/getwdcache.xml index c797bad414..8c22be9fb5 100644 --- a/docs/docbook/smbdotconf/tuning/getwdcache.xml +++ b/docs/docbook/smbdotconf/tuning/getwdcache.xml @@ -1,11 +1,14 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="GETWDCACHE"/>getwd cache (G)</term> - <listitem><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> +<samba:parameter name="getwd cache" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> - <para>Default: <command moreinfo="none">getwd cache = yes</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">getwd cache = yes</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/hostnamelookups.xml b/docs/docbook/smbdotconf/tuning/hostnamelookups.xml index daad09da8b..613fabe42f 100644 --- a/docs/docbook/smbdotconf/tuning/hostnamelookups.xml +++ b/docs/docbook/smbdotconf/tuning/hostnamelookups.xml @@ -1,14 +1,16 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="HOSTNAMELOOKUPS"/>hostname lookups (G)</term> - <listitem><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> +<samba:parameter name="hostname lookups" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> - <para>Default: <command moreinfo="none">hostname lookups = yes</command></para> + <para>Default: <command moreinfo="none">hostname lookups = yes</command></para> - <para>Example: <command moreinfo="none">hostname lookups = no</command></para> - - </listitem> - </samba:parameter> + <para>Example: <command moreinfo="none">hostname lookups = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/keepalive.xml b/docs/docbook/smbdotconf/tuning/keepalive.xml index 746cda929e..1320dfab61 100644 --- a/docs/docbook/smbdotconf/tuning/keepalive.xml +++ b/docs/docbook/smbdotconf/tuning/keepalive.xml @@ -1,16 +1,21 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="KEEPALIVE"/>keepalive (G)</term> - <listitem><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> +<samba:parameter name="keepalive" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> + <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> - <para>Default: <command moreinfo="none">keepalive = 300</command></para> - <para>Example: <command moreinfo="none">keepalive = 600</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">keepalive = 300</command></para> + + <para>Example: <command moreinfo="none">keepalive = 600</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/maxconnections.xml b/docs/docbook/smbdotconf/tuning/maxconnections.xml index 24af886b60..5127df06f4 100644 --- a/docs/docbook/smbdotconf/tuning/maxconnections.xml +++ b/docs/docbook/smbdotconf/tuning/maxconnections.xml @@ -1,16 +1,18 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="MAXCONNECTIONS"/>max connections (S)</term> - <listitem><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> +<samba:parameter name="max connections" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> + <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> - <para>Default: <command moreinfo="none">max connections = 0</command></para> - <para>Example: <command moreinfo="none">max connections = 10</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">max connections = 0</command></para> + + <para>Example: <command moreinfo="none">max connections = 10</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/maxdisksize.xml b/docs/docbook/smbdotconf/tuning/maxdisksize.xml index 8aebe91902..7d99b31e03 100644 --- a/docs/docbook/smbdotconf/tuning/maxdisksize.xml +++ b/docs/docbook/smbdotconf/tuning/maxdisksize.xml @@ -1,24 +1,28 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="MAXDISKSIZE"/>max disk size (G)</term> - <listitem><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> +<samba:parameter name="max disk size" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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>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>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> + <para>A <parameter moreinfo="none">max disk size</parameter> of 0 means no limit.</para> - <para>Default: <command moreinfo="none">max disk size = 0</command></para> - <para>Example: <command moreinfo="none">max disk size = 1000</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">max disk size = 0</command></para> + + <para>Example: <command moreinfo="none">max disk size = 1000</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/maxopenfiles.xml b/docs/docbook/smbdotconf/tuning/maxopenfiles.xml index 85b76a3378..9505b2aaa5 100644 --- a/docs/docbook/smbdotconf/tuning/maxopenfiles.xml +++ b/docs/docbook/smbdotconf/tuning/maxopenfiles.xml @@ -1,16 +1,19 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="MAXOPENFILES"/>max open files (G)</term> - <listitem><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> +<samba:parameter name="max open files" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> + <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> - <para>Default: <command moreinfo="none">max open files = 10000</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">max open files = 10000</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/maxsmbdprocesses.xml b/docs/docbook/smbdotconf/tuning/maxsmbdprocesses.xml index e46f0185ce..453818ab7d 100644 --- a/docs/docbook/smbdotconf/tuning/maxsmbdprocesses.xml +++ b/docs/docbook/smbdotconf/tuning/maxsmbdprocesses.xml @@ -1,17 +1,18 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="MAXSMBDPROCESSES"/>max smbd processes (G)</term> - <listitem><para>This parameter limits the maximum number of - <ulink url="smbd.8.html"><command moreinfo="none">smbd(8)</command></ulink> - 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> +<samba:parameter name="max smbd processes" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> - <para>Default: <command moreinfo="none">max smbd processes = 0</command> ## no limit</para> - <para>Example: <command moreinfo="none">max smbd processes = 1000</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">max smbd processes = 0</command> ## no limit</para> + + <para>Example: <command moreinfo="none">max smbd processes = 1000</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/minprintspace.xml b/docs/docbook/smbdotconf/tuning/minprintspace.xml index acbb65fa41..0df75af0ab 100644 --- a/docs/docbook/smbdotconf/tuning/minprintspace.xml +++ b/docs/docbook/smbdotconf/tuning/minprintspace.xml @@ -1,14 +1,18 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="MINPRINTSPACE"/>min print space (S)</term> - <listitem><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> +<samba:parameter name="min print space" + context="S" + print="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> - <para>See also the <link linkend="PRINTING"><parameter moreinfo="none">printing - </parameter></link> parameter.</para> + <para>See also the <link linkend="PRINTING"><parameter moreinfo="none">printing + </parameter></link> parameter.</para> - <para>Default: <command moreinfo="none">min print space = 0</command></para> - <para>Example: <command moreinfo="none">min print space = 2000</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">min print space = 0</command></para> + + <para>Example: <command moreinfo="none">min print space = 2000</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/namecachetimeout.xml b/docs/docbook/smbdotconf/tuning/namecachetimeout.xml index 0500a75c8d..6330760915 100644 --- a/docs/docbook/smbdotconf/tuning/namecachetimeout.xml +++ b/docs/docbook/smbdotconf/tuning/namecachetimeout.xml @@ -1,12 +1,15 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="NAMECACHETIMEOUT"/>name cache timeout (G)</term> - <listitem><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> +<samba:parameter name="name cache timeout" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> + <para>Default: <command moreinfo="none">name cache timeout = 660</command></para> - <para>Default: <command moreinfo="none">name cache timeout = 660</command></para> - <para>Example: <command moreinfo="none">name cache timeout = 0</command></para> - </listitem> - </samba:parameter> + <para>Example: <command moreinfo="none">name cache timeout = 0</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/paranoidserversecurity.xml b/docs/docbook/smbdotconf/tuning/paranoidserversecurity.xml index d60f179176..3fababf01b 100644 --- a/docs/docbook/smbdotconf/tuning/paranoidserversecurity.xml +++ b/docs/docbook/smbdotconf/tuning/paranoidserversecurity.xml @@ -1,16 +1,18 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="PARANOIDSERVERSECURITY"/>paranoid server security (G)</term> - <listitem><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> +<samba:parameter name="paranoid server security" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> + <para>Disabling this option prevents Samba from making + this check, which involves deliberatly attempting a + bad logon to the remote server.</para> - <para>Default: <command moreinfo="none">paranoid server security = yes</command></para> - - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">paranoid server security = yes</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/readsize.xml b/docs/docbook/smbdotconf/tuning/readsize.xml index 59c6848c76..c76b810225 100644 --- a/docs/docbook/smbdotconf/tuning/readsize.xml +++ b/docs/docbook/smbdotconf/tuning/readsize.xml @@ -1,25 +1,29 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="READSIZE"/>read size (G)</term> - <listitem><para>The option <parameter moreinfo="none">read size</parameter> - affects the overlap of disk reads/writes with network reads/writes. - If the amount of data being transferred in several of the SMB - commands (currently SMBwrite, SMBwriteX and SMBreadbraw) is larger - than this value then the server begins writing the data before it - has received the whole packet from the network, or in the case of - SMBreadbraw, it begins writing to the network before all the data - has been read from disk.</para> +<samba:parameter name="read size" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>The option <parameter moreinfo="none">read size</parameter> + affects the overlap of disk reads/writes with network reads/writes. + If the amount of data being transferred in several of the SMB + commands (currently SMBwrite, SMBwriteX and SMBreadbraw) is larger + than this value then the server begins writing the data before it + has received the whole packet from the network, or in the case of + SMBreadbraw, it begins writing to the network before all the data + has been read from disk.</para> - <para>This overlapping works best when the speeds of disk and - network access are similar, having very little effect when the - speed of one is much greater than the other.</para> + <para>This overlapping works best when the speeds of disk and + network access are similar, having very little effect when the + speed of one is much greater than the other.</para> - <para>The default value is 16384, but very little experimentation - has been done yet to determine the optimal value, and it is likely - that the best value will vary greatly between systems anyway. - A value over 65536 is pointless and will cause you to allocate - memory unnecessarily.</para> + <para>The default value is 16384, but very little experimentation + has been done yet to determine the optimal value, and it is likely + that the best value will vary greatly between systems anyway. + A value over 65536 is pointless and will cause you to allocate + memory unnecessarily.</para> - <para>Default: <command moreinfo="none">read size = 16384</command></para> - <para>Example: <command moreinfo="none">read size = 8192</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">read size = 16384</command></para> + + <para>Example: <command moreinfo="none">read size = 8192</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/socketoptions.xml b/docs/docbook/smbdotconf/tuning/socketoptions.xml index 3acc259083..5684ac5bca 100644 --- a/docs/docbook/smbdotconf/tuning/socketoptions.xml +++ b/docs/docbook/smbdotconf/tuning/socketoptions.xml @@ -1,69 +1,75 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="SOCKETOPTIONS"/>socket options (G)</term> - <listitem><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 - "Unknown socket option" 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@samba.org"> - samba@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> - - <para>Default: <command moreinfo="none">socket options = TCP_NODELAY</command></para> - <para>Example: <command moreinfo="none">socket options = IPTOS_LOWDELAY</command></para> - </listitem> - </samba:parameter> +<samba:parameter name="socket options" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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 + "Unknown socket option" 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> + + <para>Default: <command moreinfo="none">socket options = TCP_NODELAY</command></para> + + <para>Example: <command moreinfo="none">socket options = IPTOS_LOWDELAY</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/statcachesize.xml b/docs/docbook/smbdotconf/tuning/statcachesize.xml index fe7d3a7be2..0c8d4e0c72 100644 --- a/docs/docbook/smbdotconf/tuning/statcachesize.xml +++ b/docs/docbook/smbdotconf/tuning/statcachesize.xml @@ -1,9 +1,12 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="STATCACHESIZE"/>stat cache size (G)</term> - <listitem><para>This parameter determines the number of - entries in the <parameter moreinfo="none">stat cache</parameter>. You should - never need to change this parameter.</para> +<samba:parameter name="stat cache size" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter determines the number of + entries in the <parameter moreinfo="none">stat cache</parameter>. You should + never need to change this parameter.</para> - <para>Default: <command moreinfo="none">stat cache size = 50</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">stat cache size = 50</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/strictallocate.xml b/docs/docbook/smbdotconf/tuning/strictallocate.xml index 7b33ef3fc3..0d11519b04 100644 --- a/docs/docbook/smbdotconf/tuning/strictallocate.xml +++ b/docs/docbook/smbdotconf/tuning/strictallocate.xml @@ -1,21 +1,23 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="STRICTALLOCATE"/>strict allocate (S)</term> - <listitem><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> +<samba:parameter name="strict allocate" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <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>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> + <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> - <para>Default: <command moreinfo="none">strict allocate = no</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">strict allocate = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/strictsync.xml b/docs/docbook/smbdotconf/tuning/strictsync.xml index b228f7cfcb..693806a503 100644 --- a/docs/docbook/smbdotconf/tuning/strictsync.xml +++ b/docs/docbook/smbdotconf/tuning/strictsync.xml @@ -1,23 +1,25 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="STRICTSYNC"/>strict sync (S)</term> - <listitem><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> +<samba:parameter name="strict sync" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> - <para>See also the <link linkend="SYNCALWAYS"><parameter moreinfo="none">sync - always></parameter></link> parameter.</para> + <para>See also the <link linkend="SYNCALWAYS"><parameter moreinfo="none">sync + always></parameter></link> parameter.</para> - <para>Default: <command moreinfo="none">strict sync = no</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">strict sync = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/syncalways.xml b/docs/docbook/smbdotconf/tuning/syncalways.xml index c5c32343a7..dca33eb802 100644 --- a/docs/docbook/smbdotconf/tuning/syncalways.xml +++ b/docs/docbook/smbdotconf/tuning/syncalways.xml @@ -1,19 +1,21 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="SYNCALWAYS"/>sync always (S)</term> - <listitem><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> +<samba:parameter name="sync always" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> - <para>See also the <link linkend="STRICTSYNC"><parameter moreinfo="none">strict - sync</parameter></link> parameter.</para> + <para>See also the <link linkend="STRICTSYNC"><parameter moreinfo="none">strict + sync</parameter></link> parameter.</para> - <para>Default: <command moreinfo="none">sync always = no</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">sync always = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/usemmap.xml b/docs/docbook/smbdotconf/tuning/usemmap.xml index 46fa4600de..1e79e07ef3 100644 --- a/docs/docbook/smbdotconf/tuning/usemmap.xml +++ b/docs/docbook/smbdotconf/tuning/usemmap.xml @@ -1,14 +1,17 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="USEMMAP"/>use mmap (G)</term> - <listitem><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> +<samba:parameter name="use mmap" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <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> - <para>Default: <command moreinfo="none">use mmap = yes</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">use mmap = yes</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/usesendfile.xml b/docs/docbook/smbdotconf/tuning/usesendfile.xml index 5f2dcb72a9..6bbd651549 100644 --- a/docs/docbook/smbdotconf/tuning/usesendfile.xml +++ b/docs/docbook/smbdotconf/tuning/usesendfile.xml @@ -1,14 +1,15 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="USESENDFILE"/>use sendfile (S)</term> - <listitem><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. - </para> +<samba:parameter name="use sendfile" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <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.</para> - <para>Default: <command moreinfo="none">use sendfile = no</command></para> - </listitem> - </samba:parameter> + <para>Default: <command moreinfo="none">use sendfile = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/tuning/writecachesize.xml b/docs/docbook/smbdotconf/tuning/writecachesize.xml index b54a0e4fd6..8b5fbe66bd 100644 --- a/docs/docbook/smbdotconf/tuning/writecachesize.xml +++ b/docs/docbook/smbdotconf/tuning/writecachesize.xml @@ -1,27 +1,30 @@ -<samba:parameter xmlns:samba="http://samba.org/common"> - <term><anchor id="WRITECACHESIZE"/>write cache size (S)</term> - <listitem><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> +<samba:parameter name="write cache size" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <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>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> + <para>The integer parameter specifies the size of this cache + (per oplocked file) in bytes.</para> - <para>Default: <command moreinfo="none">write cache size = 0</command></para> - <para>Example: <command moreinfo="none">write cache size = 262144</command></para> + <para>Default: <command moreinfo="none">write cache size = 0</command></para> - <para>for a 256k cache size per file.</para> - </listitem> - </samba:parameter> + <para>Example: <command moreinfo="none">write cache size = 262144</command></para> + + <para>for a 256k cache size per file.</para> +</listitem> +</samba:parameter> |