1<?xml version="1.0"?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5<refentry id="sysctl.d"
6    xmlns:xi="http://www.w3.org/2001/XInclude">
7
8  <refentryinfo>
9    <title>sysctl.d</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>sysctl.d</refentrytitle>
15    <manvolnum>5</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>sysctl.d</refname>
20    <refpurpose>Configure kernel parameters at boot</refpurpose>
21  </refnamediv>
22
23  <refsynopsisdiv>
24    <para><filename>/etc/sysctl.d/*.conf</filename></para>
25    <para><filename>/run/sysctl.d/*.conf</filename></para>
26    <para><filename>/usr/lib/sysctl.d/*.conf</filename></para>
27
28    <programlisting>key.name.under.proc.sys = some value
29key/name/under/proc/sys = some value
30key/middle.part.with.dots/foo = 123
31key.middle/part/with/dots.foo = 123
32-key.that.will.not.fail = value
33key.pattern.*.with.glob = whatever
34-key.pattern.excluded.with.glob
35key.pattern.overridden.with.glob = custom
36</programlisting>
37  </refsynopsisdiv>
38
39  <refsect1>
40    <title>Description</title>
41
42    <para>At boot,
43    <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
44    reads configuration files from the above directories to configure
45    <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
46    kernel parameters.</para>
47  </refsect1>
48
49  <refsect1>
50    <title>Configuration Format</title>
51
52    <para>The configuration files contain a list of variable
53    assignments, separated by newlines. Empty lines and lines whose
54    first non-whitespace character is <literal>#</literal> or
55    <literal>;</literal> are ignored.</para>
56
57    <para>Note that either <literal>/</literal> or <literal>.</literal> may be used as separators within
58    sysctl variable names. If the first separator is a slash, remaining slashes and dots are left intact. If
59    the first separator is a dot, dots and slashes are interchanged.
60    <literal>kernel.domainname=foo</literal> and <literal>kernel/domainname=foo</literal> are equivalent and
61    will cause <literal>foo</literal> to be written to
62    <filename>/proc/sys/kernel/domainname</filename>. Either
63    <literal>net.ipv4.conf.enp3s0/200.forwarding</literal> or
64    <literal>net/ipv4/conf/enp3s0.200/forwarding</literal> may be used to refer to
65    <filename>/proc/sys/net/ipv4/conf/enp3s0.200/forwarding</filename>. A glob
66    <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> pattern may be
67    used to write the same value to all matching keys. Keys for which an explicit pattern exists will be
68    excluded from any glob matching. In addition, a key may be explicitly excluded from being set by any
69    matching glob patterns by specifying the key name prefixed with a <literal>-</literal> character and not
70    followed by <literal>=</literal>, see SYNOPSIS.</para>
71
72    <para>Any access permission errors and attempts to write variables not present on the local system are
73    logged at debug level and do not cause the service to fail. Other types of errors when setting variables
74    are logged with higher priority and cause the service to return failure at the end (after processing
75    other variables). As an exception, if a variable assignment is prefixed with a single
76    <literal>-</literal> character, failure to set the variable for any reason will be logged at debug level
77    and will not cause the service to fail.</para>
78
79    <para>The settings configured with <filename>sysctl.d</filename> files will be applied early on boot. The
80    network interface-specific options will also be applied individually for each network interface as it
81    shows up in the system. (More specifically, <filename>net.ipv4.conf.*</filename>,
82    <filename>net.ipv6.conf.*</filename>, <filename>net.ipv4.neigh.*</filename> and
83    <filename>net.ipv6.neigh.*</filename>).</para>
84
85    <para>Many sysctl parameters only become available when certain
86    kernel modules are loaded. Modules are usually loaded on demand,
87    e.g. when certain hardware is plugged in or network brought up.
88    This means that
89    <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
90    which runs during early boot will not configure such parameters if
91    they become available after it has run. To set such parameters, it
92    is recommended to add an
93    <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
94    rule to set those parameters when they become available.
95    Alternatively, a slightly simpler and less efficient option is to
96    add the module to
97    <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
98    causing it to be loaded statically before sysctl settings are
99    applied (see example below).</para>
100  </refsect1>
101
102  <xi:include href="standard-conf.xml" xpointer="confd" />
103
104  <refsect1>
105    <title>Examples</title>
106    <example>
107      <title>Set kernel YP domain name</title>
108      <para><filename>/etc/sysctl.d/domain-name.conf</filename>:
109      </para>
110
111      <programlisting>kernel.domainname=example.com</programlisting>
112    </example>
113
114    <example>
115      <title>Apply settings available only when a certain module is loaded (method one)</title>
116      <para><filename>/etc/udev/rules.d/99-bridge.rules</filename>:
117      </para>
118
119      <programlisting>ACTION=="add", SUBSYSTEM=="module", KERNEL=="br_netfilter", \
120      RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/net/bridge"
121</programlisting>
122
123      <para><filename>/etc/sysctl.d/bridge.conf</filename>:
124      </para>
125
126      <programlisting>net.bridge.bridge-nf-call-ip6tables = 0
127net.bridge.bridge-nf-call-iptables = 0
128net.bridge.bridge-nf-call-arptables = 0
129</programlisting>
130
131      <para>This method applies settings when the module is
132      loaded. Please note that, unless the <filename>br_netfilter</filename>
133      module is loaded, bridged packets will not be filtered by
134      Netfilter (starting with kernel 3.18), so simply not loading the
135      module is sufficient to avoid filtering.</para>
136    </example>
137
138    <example>
139      <title>Apply settings available only when a certain module is loaded (method two)</title>
140      <para><filename>/etc/modules-load.d/bridge.conf</filename>:
141      </para>
142
143      <programlisting>br_netfilter</programlisting>
144
145      <para><filename>/etc/sysctl.d/bridge.conf</filename>:
146      </para>
147
148      <programlisting>net.bridge.bridge-nf-call-ip6tables = 0
149net.bridge.bridge-nf-call-iptables = 0
150net.bridge.bridge-nf-call-arptables = 0
151</programlisting>
152
153      <para>This method forces the module to be always loaded. Please
154      note that, unless the <filename>br_netfilter</filename> module is
155      loaded, bridged packets will not be filtered with Netfilter
156      (starting with kernel 3.18), so simply not loading the module is
157      sufficient to avoid filtering.</para>
158    </example>
159
160    <example>
161      <title>Set network routing properties for all interfaces</title>
162      <para><filename>/etc/sysctl.d/20-rp_filter.conf</filename>:</para>
163
164      <programlisting>net.ipv4.conf.default.rp_filter = 2
165net.ipv4.conf.*.rp_filter = 2
166-net.ipv4.conf.all.rp_filter
167net.ipv4.conf.hub0.rp_filter = 1
168</programlisting>
169
170      <para>The <option>rp_filter</option> key will be set to "2" for all interfaces, except "hub0". We set
171      <filename>net.ipv4.conf.default.rp_filter</filename> first, so any interfaces which are added
172      <emphasis>later</emphasis> will get this value (this also covers any interfaces detected while we're
173      running). The glob matches any interfaces which were detected <emphasis>earlier</emphasis>. The glob
174      will also match <filename>net.ipv4.conf.all.rp_filter</filename>, which we don't want to set at all, so
175      it is explicitly excluded. And "hub0" is excluded from the glob because it has an explicit setting.
176      </para>
177    </example>
178
179  </refsect1>
180
181  <refsect1>
182    <title>See Also</title>
183    <para>
184      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
185      <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
186      <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
187      <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
188      <citerefentry project='man-pages'><refentrytitle>sysctl.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
189      <citerefentry project='man-pages'><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry>
190    </para>
191  </refsect1>
192
193</refentry>
194