Adding upstream version 2:4.17.12+dfsg.upstream/2%4.17.12+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 104 insertions, 0 deletions

diff --git a/docs-xml/smbdotconf/tuning/socketoptions.xml b/docs-xml/smbdotconf/tuning/socketoptions.xml
new file mode 100644
index 0000000..d2be514
--- /dev/null
+++ b/docs-xml/smbdotconf/tuning/socketoptions.xml
@@ -0,0 +1,104 @@
+<samba:parameter name="socket options"
+                 context="G"
+				 type="string"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+    <para>
+        <warning>
+        <para>Modern server operating systems are tuned for high
+        network performance in the majority of situations; when you set socket
+        options you are overriding those settings.  Linux in particular has an
+        auto-tuning mechanism for buffer sizes that will be disabled if you
+        specify a socket buffer size.  This can potentially cripple your
+        TCP/IP stack.</para>
+
+        <para> Getting the socket options correct can make a big difference to
+        your performance, but getting them wrong can degrade it by just as
+        much.  As with any other low level setting, if you must make changes
+        to it, make small changes and <emphasis>test</emphasis> the effect
+        before making any large changes.</para>
+        </warning>
+    </para>
+
+    <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@lists.samba.org">
+    samba-technical@lists.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>TCP_KEEPCNT *</para></listitem>
+	<listitem><para>TCP_KEEPIDLE *</para></listitem>
+	<listitem><para>TCP_KEEPINTVL *</para></listitem>
+    	<listitem><para>IPTOS_LOWDELAY</para></listitem>
+    	<listitem><para>IPTOS_THROUGHPUT</para></listitem>
+	<listitem><para>SO_REUSEPORT</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>
+	<listitem><para>SO_SNDTIMEO *</para></listitem>
+	<listitem><para>SO_RCVTIMEO *</para></listitem>
+	<listitem><para>TCP_FASTACK *</para></listitem>
+	<listitem><para>TCP_QUICKACK</para></listitem>
+	<listitem><para>TCP_NODELAYACK</para></listitem>
+	<listitem><para>TCP_KEEPALIVE_THRESHOLD *</para></listitem>
+	<listitem><para>TCP_KEEPALIVE_ABORT_THRESHOLD *</para></listitem>
+	<listitem><para>TCP_DEFER_ACCEPT *</para></listitem>
+	<listitem><para>TCP_USER_TIMEOUT *</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>