man: fix file extension in udev rules example

[elogind.git] / man / sysctl.d.xml

diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml
index a4a495ee32b4a473efa30f5d7ccdd3a9e07a7f61..5529fc98bf487e795e5145dbf20e385f964c0d1b 100644 (file)
--- a/man/sysctl.d.xml
+++ b/man/sysctl.d.xml
@@ -54,34 +54,29 @@
         <refsect1>
                 <title>Description</title>
 
         <refsect1>
                 <title>Description</title>
 

-               <para>At boot,
-               <citerefentry><refentrytitle>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-               reads configuration files from the above directories
-               to configure
-               <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-               kernel parameters.</para>
+                <para>At boot,
+                <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                reads configuration files from the above directories
+                to configure
+                <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                kernel parameters.</para>

         </refsect1>
 
         <refsect1>
         </refsect1>
 
         <refsect1>

-               <title>Configuration Format</title>
+                <title>Configuration Format</title>

 
 

-               <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>
+                <para>The configuration files contain a list of
+                variable assignments, separated by newlines. Empty
+                lines and lines whose first non-whitespace character
+                is <literal>#</literal> or <literal>;</literal> are
+                ignored.</para>

 
                 <para>Each configuration file shall be named in the
 
                 <para>Each configuration file shall be named in the

-                style of <filename>&lt;program&gt;.conf</filename>.
+                style of <filename><replaceable>program</replaceable>.conf</filename>.

                 Files in <filename>/etc/</filename> override files
                 with the same name in <filename>/usr/lib/</filename>
                 and <filename>/run/</filename>.  Files in
                 Files in <filename>/etc/</filename> override files
                 with the same name in <filename>/usr/lib/</filename>
                 and <filename>/run/</filename>.  Files in

-                <filename>/run</filename> override files with the same
+                <filename>/run/</filename> override files with the same

                 name in <filename>/usr/lib/</filename>. Packages
                 should install their configuration files in
                 <filename>/usr/lib/</filename>. Files in
                 name in <filename>/usr/lib/</filename>. Packages
                 should install their configuration files in
                 <filename>/usr/lib/</filename>. Files in


@@ -89,27 +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
                 administrator, who may use this logic to override the
                 configuration files installed by vendor packages. All
                 configuration files are sorted by their filename in

-                alphabetical order, regardless in which of the
-                directories they reside, to guarantee that a specific
-                configuration file takes precedence over another file
-                with an alphabetically earlier name, if both files
-                contain the same variable setting.</para>
+                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
 
                 <para>If the administrator wants to disable a

-                configuration file supplied by the vendor the
+                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
                 recommended way is to place a symlink to
                 <filename>/dev/null</filename> in
                 <filename>/etc/sysctl.d/</filename> bearing the

-                same file name.</para>
+                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>
         </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>Disable packet filter on bridged packets (method one)</title>
+                        <para><filename>/etc/udev/rules.d/99-bridge.rules</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>
                 <example>

-                        <title>/etc/sysctl.d/domain-name.conf example:</title>
+                        <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>
 
                 </example>
         </refsect1>
 


@@ -121,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>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>
 
                 </para>
         </refsect1>