summaryrefslogtreecommitdiff
path: root/docs-xml/smbdotconf/tuning/socketoptions.xml
blob: 27ae5fd32bc6483fd0572b68b03a24700c904431 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
<samba:parameter name="socket options"
                 context="G"
				 type="list"
                 developer="1"
                 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@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>