X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsysctl.d.xml;h=dd73f922363081ab76f68570d1557782e4a5d113;hp=854864cffcb86c695b70c1904a63775f587830f3;hb=d532366133a29136ad2dd95cb9268c7bbbb4d3ee;hpb=79640424059328268b9fb6c5fa8eb777b27a177e

diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml
index 854864cff..dd73f9223 100644
--- a/man/sysctl.d.xml
+++ b/man/sysctl.d.xml
@@ -68,13 +68,8 @@
                 <para>The configuration files contain a list of
                 variable assignments, separated by newlines. Empty
                 lines and lines whose first non-whitespace character
-                is # or ; are ignored.</para>
-
-                <para>Note that both / and . are accepted as label
-                separators within sysctl variable
-                names. <literal>kernel.domainname=foo</literal> and
-                <literal>kernel/domainname=foo</literal> hence are
-                entirely equivalent.</para>
+                is <literal>#</literal> or <literal>;</literal> are
+                ignored.</para>
 
                 <para>Each configuration file shall be named in the
                 style of <filename><replaceable>program</replaceable>.conf</filename>.
@@ -89,29 +84,106 @@
                 administrator, who may use this logic to override the
                 configuration files installed by vendor packages. All
                 configuration files are sorted by their filename in
-                lexicographic order, regardless in which of the
-                directories they reside. If multiple files specify the
+                lexicographic order, regardless of which of the
+                directories they reside in. If multiple files specify the
                 same variable name, the entry in the file with the
                 lexicographically latest name will be applied. It is
                 recommended to prefix all filenames with a two-digit
                 number and a dash, to simplify the ordering of the
                 files.</para>
 
+                <para>Note that either <literal>/</literal> or
+                <literal>.</literal> may be used as separators within
+                sysctl variable names. If the first separator is a
+                slash, remaining slashes and dots are left intact. If
+                the first separator is a dot, dots and slashes are
+                interchanged. <literal>kernel.domainname=foo</literal>
+                and <literal>kernel/domainname=foo</literal> are
+                equivalent and will cause <literal>foo</literal> to
+                be written to
+                <filename>/proc/sys/kernel/domainname</filename>.
+                Either
+                <literal>net.ipv4.conf.enp3s0/200.forwarding</literal>
+                or
+                <literal>net/ipv4/conf/enp3s0.200/forwarding</literal>
+                may be used to refer to
+                <filename>/proc/sys/net/ipv4/conf/enp3s0.200/forwarding</filename>.
+                </para>
+
                 <para>If the administrator wants to disable a
                 configuration file supplied by the vendor, the
                 recommended way is to place a symlink to
                 <filename>/dev/null</filename> in
                 <filename>/etc/sysctl.d/</filename> bearing the
                 same filename.</para>
+
+                <para>The settings configured with
+                <filename>sysctl.d</filename> files will be applied
+                early on boot. The network interface-specific options
+                will also be applied individually for each network
+                interface as it shows up in the system. (More
+                specifically,
+                <filename>net.ipv4.conf.*</filename>,
+                <filename>net.ipv6.conf.*</filename>,
+                <filename>net.ipv4.neigh.*</filename> and <filename>net.ipv6.neigh.*</filename>).</para>
+
+                <para>Many sysctl parameters only become available
+                when certain kernel modules are loaded. Modules are
+                usually loaded on demand, e.g. when certain hardware
+                is plugged in or network brought up. This means that
+                <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> which runs
+                during early boot will not configure such parameters
+                if they become available after it has run. To
+                set such parameters, it is recommended to add
+                an <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> rule to set those parameters when they become
+                available. Alternatively, a slightly simpler and
+                less efficient option is to add the module to
+                <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, causing it to be loaded statically
+                before sysctl settings are applied (see
+                example below).</para>
         </refsect1>
 
         <refsect1>
-                <title>Example</title>
+                <title>Examples</title>
+                <example>
+                        <title>Set kernel YP domain name</title>
+                        <para><filename>/etc/sysctl.d/domain-name.conf</filename>:
+                        </para>
+
+                        <programlisting>kernel.domainname=example.com</programlisting>
+                </example>
+
                 <example>
-                        <title>/etc/sysctl.d/domain-name.conf example:</title>
+                        <title>Disable packet filter on bridged packets (method one)</title>
+                        <para><filename>/etc/udev/rules.d/99-bridge.conf</filename>:
+                        </para>
+
+                        <programlisting>ACTION=="add", SUBSYSTEM=="module", KERNEL=="bridge", RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/proc/sys/net/bridge"
+</programlisting>
+
+                        <para><filename>/etc/sysctl.d/bridge.conf</filename>:
+                        </para>
+
+                        <programlisting>net.bridge.bridge-nf-call-ip6tables = 0
+net.bridge.bridge-nf-call-iptables = 0
+net.bridge.bridge-nf-call-arptables = 0
+</programlisting>
+                </example>
+
+                <example>
+                        <title>Disable packet filter on bridged packets (method two)</title>
+                        <para><filename>/etc/modules-load.d/bridge.conf</filename>:
+                        </para>
+
+                        <programlisting>bridge</programlisting>
+
+                        <para><filename>/etc/sysctl.d/bridge.conf</filename>:
+                        </para>
 
-                        <programlisting># Set kernel YP domain name
-kernel.domainname=example.com</programlisting>
+                        <programlisting>net.bridge.bridge-nf-call-ip6tables = 0
+net.bridge.bridge-nf-call-iptables = 0
+net.bridge.bridge-nf-call-arptables = 0
+</programlisting>
                 </example>
         </refsect1>
 
@@ -123,6 +195,7 @@ kernel.domainname=example.com</programlisting>
                         <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sysctl.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                 </para>
         </refsect1>