Merge pull request #4123 from keszybz/network-file-dropins

Network file dropins

3 files changed, 123 insertions, 107 deletions

diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml
index 78f0e25a6f..c8b5a057f8 100644
--- a/man/systemd.netdev.xml
+++ b/man/systemd.netdev.xml
@@ -58,31 +58,38 @@
     <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
     </para>
 
-    <para>Virtual Network Device files must have the extension
-    <filename>.netdev</filename>; other extensions are ignored.
-    Virtual network devices are created as soon as networkd is
-    started. If a netdev with the specified name already exists,
-    networkd will use that as-is rather than create its own. Note that
-    the settings of the pre-existing netdev will not be changed by
+    <para>The main Virtual Network Device file must have the extension <filename>.netdev</filename>;
+    other extensions are ignored. Virtual network devices are created as soon as networkd is
+    started. If a netdev with the specified name already exists, networkd will use that as-is rather
+    than create its own. Note that the settings of the pre-existing netdev will not be changed by
     networkd.</para>
 
-    <para>The <filename>.netdev</filename> files are read from the
-    files located in the system network directory
-    <filename>/usr/lib/systemd/network</filename>, the volatile
-    runtime network directory
-    <filename>/run/systemd/network</filename> and the local
-    administration network directory
-    <filename>/etc/systemd/network</filename>. All configuration files
-    are collectively sorted and processed in lexical order, regardless
-    of the directories in which they live. However, files with
-    identical filenames replace each other. Files in
-    <filename>/etc</filename> have the highest priority, files in
-    <filename>/run</filename> take precedence over files with the same
-    name in <filename>/usr/lib</filename>. This can be used to
-    override a system-supplied configuration file with a local file if
-    needed. As a special case, an empty file (file size 0) or symlink
-    with the same name pointing to <filename>/dev/null</filename>
-    disables the configuration file entirely (it is "masked").</para>
+    <para>The <filename>.netdev</filename> files are read from the files located in the system
+    network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network
+    directory <filename>/run/systemd/network</filename> and the local administration network
+    directory <filename>/etc/systemd/network</filename>. All configuration files are collectively
+    sorted and processed in lexical order, regardless of the directories in which they live.
+    However, files with identical filenames replace each other. Files in <filename>/etc</filename>
+    have the highest priority, files in <filename>/run</filename> take precedence over files with
+    the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied
+    configuration file with a local file if needed. As a special case, an empty file (file size 0)
+    or symlink with the same name pointing to <filename>/dev/null</filename> disables the
+    configuration file entirely (it is "masked").</para>
+
+    <para>Along with the netdev file <filename>foo.netdev</filename>, a "drop-in" directory
+    <filename>foo.netdev.d/</filename> may exist. All files with the suffix <literal>.conf</literal>
+    from this directory will be parsed after the file itself is parsed. This is useful to alter or
+    add configuration settings, without having to modify the main configuration file. Each drop-in
+    file must have appropriate section headers.</para>
+
+    <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal>
+    directories can be placed in <filename>/usr/lib/systemd/network</filename> or
+    <filename>/run/systemd/network</filename> directories. Drop-in files in
+    <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn
+    take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these
+    directories take precedence over the main netdev file wherever located. (Of course, since
+    <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is
+    unlikely drop-ins should be used in either of those places.)</para>
   </refsect1>
 
   <refsect1>
diff --git a/man/systemd.network.xml b/man/systemd.network.xml
index c332cd7bdc..eb7d441842 100644
--- a/man/systemd.network.xml
+++ b/man/systemd.network.xml
@@ -58,31 +58,40 @@
     <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
     </para>
 
-    <para>Network files must have the extension
-    <filename>.network</filename>; other extensions are ignored.
-    Networks are applied to links whenever the links appear.</para>
-
-    <para>The <filename>.network</filename> files are read from the
-    files located in the system network directory
-    <filename>/usr/lib/systemd/network</filename>, the volatile
-    runtime network directory
-    <filename>/run/systemd/network</filename> and the local
-    administration network directory
-    <filename>/etc/systemd/network</filename>. All configuration files
-    are collectively sorted and processed in lexical order, regardless
-    of the directories in which they live. However, files with
-    identical filenames replace each other. Files in
-    <filename>/etc</filename> have the highest priority, files in
-    <filename>/run</filename> take precedence over files with the same
-    name in <filename>/usr/lib</filename>. This can be used to
-    override a system-supplied configuration file with a local file if
-    needed. As a special case, an empty file (file size 0) or symlink
-    with the same name pointing to <filename>/dev/null</filename>
-    disables the configuration file entirely (it is "masked").</para>
-
-    <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 nor IPv6LL enabled,
-    shall be considered to have no IPv6 support. IPv6 will be automatically disabled for that interface by writing "1"
-    to <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>.
+    <para>The main network file must have the extension <filename>.network</filename>; other
+    extensions are ignored. Networks are applied to links whenever the links appear.</para>
+
+    <para>The <filename>.network</filename> files are read from the files located in the system
+    network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network
+    directory <filename>/run/systemd/network</filename> and the local administration network
+    directory <filename>/etc/systemd/network</filename>. All configuration files are collectively
+    sorted and processed in lexical order, regardless of the directories in which they live.
+    However, files with identical filenames replace each other. Files in <filename>/etc</filename>
+    have the highest priority, files in <filename>/run</filename> take precedence over files with
+    the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied
+    configuration file with a local file if needed. As a special case, an empty file (file size 0)
+    or symlink with the same name pointing to <filename>/dev/null</filename> disables the
+    configuration file entirely (it is "masked").</para>
+
+    <para>Along with the network file <filename>foo.network</filename>, a "drop-in" directory
+    <filename>foo.network.d/</filename> may exist. All files with the suffix
+    <literal>.conf</literal> from this directory will be parsed after the file itself is
+    parsed. This is useful to alter or add configuration settings, without having to modify the main
+    configuration file. Each drop-in file must have appropriate section headers.</para>
+
+    <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal>
+    directories can be placed in <filename>/usr/lib/systemd/network</filename> or
+    <filename>/run/systemd/network</filename> directories. Drop-in files in
+    <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn
+    take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these
+    directories take precedence over the main netdev file wherever located. (Of course, since
+    <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is
+    unlikely drop-ins should be used in either of those places.)</para>
+
+    <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6
+    nor IPv6LL enabled, shall be considered to have no IPv6 support. IPv6 will be automatically
+    disabled for that interface by writing "1" to
+    <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>.
     </para>
   </refsect1>
 
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index f818e772a9..9778283fec 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -144,71 +144,71 @@
     <option>false</option> and <option>off</option> are
     equivalent.</para>
 
-    <para>Time span values encoded in unit files can be written in various formats. A stand-alone number specifies a
-    time in seconds.  If suffixed with a time unit, the unit is honored. A concatenation of multiple values with units
-    is supported, in which case the values are added up. Example: <literal>50</literal> refers to 50 seconds;
-    <literal>2min 200ms</literal> refers to 2 minutes and 200 milliseconds, i.e. 120200 ms.  The following time units
-    are understood: <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>,
+    <para>Time span values encoded in unit files can be written in various formats. A stand-alone
+    number specifies a time in seconds.  If suffixed with a time unit, the unit is honored. A
+    concatenation of multiple values with units is supported, in which case the values are added
+    up. Example: <literal>50</literal> refers to 50 seconds; <literal>2min 200ms</literal> refers to
+    2 minutes and 200 milliseconds, i.e. 120200 ms.  The following time units are understood:
+    <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>,
     <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>.  For details see
     <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 
-    <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored. This may be
-    used for commenting. Lines ending in a backslash are concatenated with the following line while reading and the
-    backslash is replaced by a space character. This may be used to wrap long lines.</para>
-
-    <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name
-    in one of the unit search paths. For example, <filename>systemd-networkd.service</filename> has the alias
-    <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the symlink
-    <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In addition, unit files may
-    specify aliases through the <varname>Alias=</varname> directive in the [Install] section; those aliases are only
-    effective when the unit is enabled. When the unit is enabled, symlinks will be created for those names, and removed
-    when the unit is disabled. For example, <filename>reboot.target</filename> specifies
-    <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever CTRL+ALT+DEL is
-    pressed. Alias names may be used in commands like <command>enable</command>, <command>disable</command>,
-    <command>start</command>, <command>stop</command>, <command>status</command>, …, and in unit dependency directives
-    <varname>Wants=</varname>, <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …,
-    with the limitation that aliases specified through <varname>Alias=</varname> are only effective when the unit is
-    enabled. Aliases cannot be used with the <command>preset</command> command.</para>
-
-    <para>Along with a unit file <filename>foo.service</filename>, the
-    directory <filename>foo.service.wants/</filename> may exist. All
-    unit files symlinked from such a directory are implicitly added as
-    dependencies of type <varname>Wants=</varname> to the unit. This
-    is useful to hook units into the start-up of other units, without
-    having to modify their unit files. For details about the semantics
-    of <varname>Wants=</varname>, see below. The preferred way to
-    create symlinks in the <filename>.wants/</filename> directory of a
-    unit file is with the <command>enable</command> command of the
+    <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are
+    ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the
+    following line while reading and the backslash is replaced by a space character. This may be
+    used to wrap long lines.</para>
+
+    <para>Units can be aliased (have an alternative name), by creating a symlink from the new name
+    to the existing name in one of the unit search paths. For example,
+    <filename>systemd-networkd.service</filename> has the alias
+    <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the
+    symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In
+    addition, unit files may specify aliases through the <varname>Alias=</varname> directive in the
+    [Install] section; those aliases are only effective when the unit is enabled. When the unit is
+    enabled, symlinks will be created for those names, and removed when the unit is disabled. For
+    example, <filename>reboot.target</filename> specifies
+    <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever
+    CTRL+ALT+DEL is pressed. Alias names may be used in commands like <command>enable</command>,
+    <command>disable</command>, <command>start</command>, <command>stop</command>,
+    <command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>,
+    <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the
+    limitation that aliases specified through <varname>Alias=</varname> are only effective when the
+    unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para>
+
+    <para>Along with a unit file <filename>foo.service</filename>, the directory
+    <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a
+    directory are implicitly added as dependencies of type <varname>Wants=</varname> to the unit.
+    This is useful to hook units into the start-up of other units, without having to modify their
+    unit files. For details about the semantics of <varname>Wants=</varname>, see below. The
+    preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is
+    with the <command>enable</command> command of the
     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    tool which reads information from the [Install] section of unit
-    files (see below). A similar functionality exists for
-    <varname>Requires=</varname> type dependencies as well, the
-    directory suffix is <filename>.requires/</filename> in this
-    case.</para>
+    tool which reads information from the [Install] section of unit files (see below). A similar
+    functionality exists for <varname>Requires=</varname> type dependencies as well, the directory
+    suffix is <filename>.requires/</filename> in this case.</para>
 
     <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
-    <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this
-    directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings for
-    a unit, without having to modify unit files. Each drop-in file must have appropriate section headers. Note that for
-    instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory and read its
-    <literal>.conf</literal> files, followed by the template <literal>.d/</literal> subdirectory and the
-    <literal>.conf</literal> files there. Also note that settings from the <literal>[Install]</literal> section are not
-    honoured in drop-in unit files, and have no effect.</para>
-
-    <para>In addition to <filename>/etc/systemd/system</filename>,
-    the drop-in <literal>.conf</literal> files for system services
-    can be placed in <filename>/usr/lib/systemd/system</filename> or
-    <filename>/run/systemd/system</filename> directories. Drop-in
-    files in <filename>/etc</filename> take precedence over those in
-    <filename>/run</filename> which in turn take precedence over
-    those in <filename>/usr/lib</filename>. Drop-in files under any of
-    these directories take precedence over unit files wherever located.
-    (Of course, since <filename>/run</filename> is temporary and
-    <filename>/usr/lib</filename> is for vendors, it is unlikely
-    drop-ins should be used in either of those places.)</para>
-    <!-- Note that we do not document .include here, as we
-         consider it mostly obsolete, and want people to
-         use .d/ drop-ins instead. -->
+    <filename>foo.service.d/</filename> may exist. All files with the suffix
+    <literal>.conf</literal> from this directory will be parsed after the file itself is
+    parsed. This is useful to alter or add configuration settings for a unit, without having to
+    modify unit files. Each drop-in file must have appropriate section headers. Note that for
+    instantiated units, this logic will first look for the instance <literal>.d/</literal>
+    subdirectory and read its <literal>.conf</literal> files, followed by the template
+    <literal>.d/</literal> subdirectory and the <literal>.conf</literal> files there. Also note that
+    settings from the <literal>[Install]</literal> section are not honoured in drop-in unit files,
+    and have no effect.</para>
+
+    <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d</literal>
+    directories for system services can be placed in <filename>/usr/lib/systemd/system</filename> or
+    <filename>/run/systemd/system</filename> directories. Drop-in files in <filename>/etc</filename>
+    take precedence over those in <filename>/run</filename> which in turn take precedence over those
+    in <filename>/usr/lib</filename>. Drop-in files under any of these directories take precedence
+    over unit files wherever located.  (Of course, since <filename>/run</filename> is temporary and
+    <filename>/usr/lib</filename> is for vendors, it is unlikely drop-ins should be used in either
+    of those places.)</para>
+
+    <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want
+         people to use .d/ drop-ins instead. -->
 
     <para>Some unit names reflect paths existing in the file system
     namespace. Example: a device unit