From cc9b6bdc96e157e6ee9e4dc1d0a304a9df601564 Mon Sep 17 00:00:00 2001
From: Yu Watanabe <watanabe.yu+github@gmail.com>
Date: Mon, 18 Apr 2022 03:08:55 +0900
Subject: [PATCH] man: recommend that .network or friends should have a numeric
 prefix

Closes #23105.
---
 man/systemd.link.xml    | 35 +++++++++++++++++++++--------------
 man/systemd.netdev.xml  | 30 ++++++++++++++++++------------
 man/systemd.network.xml | 15 ++++++++++-----
 3 files changed, 49 insertions(+), 31 deletions(-)

diff --git a/man/systemd.link.xml b/man/systemd.link.xml
index 5629057bf26..de23b941ad2 100644
--- a/man/systemd.link.xml
+++ b/man/systemd.link.xml
@@ -32,15 +32,19 @@
     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> for a
     general description of the syntax.</para>
 
-    <para>The link files are read from the files located in the system network directory
-    <filename>/usr/lib/systemd/network</filename>, the volatile runtime network directory
+    <para>The <filename>.link</filename> files are read from the files located in the system network
+    directory <filename>/usr/lib/systemd/network</filename> and
+    <filename>/usr/local/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>. Link files must have the extension
-    <filename>.link</filename>; other extensions are ignored. All link 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 link file with a
+    <filename>/etc/systemd/network</filename>. All configuration files are collectively sorted and
+    processed in alphanumeric order, regardless of the directories in which they live. However, files
+    with identical filenames replace each other. It is recommended that each filename is prefixed with
+    a number (e.g. <filename>10-eth0.link</filename>). Otherwise, the default
+    <filename>.link</filename> files or those generated by
+    <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    may take precedence over user configured files. 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 link 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>
@@ -71,13 +75,13 @@
   <refsect1>
     <title>[Match] Section Options</title>
 
-    <para>A link file is said to match a device if all matches specified by the
-    [Match] section are satisfied. When a link file does not contain valid settings
-    in [Match] section, then the file will match all devices and
-    <command>systemd-udevd</command> warns about that. Hint: to avoid the warning and to make it clear
-    that all interfaces shall be matched, add the following:
+    <para>A link file is said to match an interface if all matches specified by the [Match] section are
+    satisfied. When a link file does not contain valid settings in [Match] section, then the file will
+    match all interfaces and <command>systemd-udevd</command> warns about that. Hint: to avoid the
+    warning and to make it clear that all interfaces shall be matched, add the following:
     <programlisting>OriginalName=*</programlisting>
-    The following keys are accepted:</para>
+    The first (in alphanumeric order) of the link files that matches a given interface is applied, all
+    later files are ignored, even if they match as well. The following keys are accepted:</para>
 
     <variablelist class='network-directives'>
       <!-- This list is reused in systemd.network(3), hence maintain a specific order:
@@ -1211,6 +1215,9 @@ MACAddress=cb:a9:87:65:43:21</programlisting>
       </citerefentry>,
       <citerefentry>
         <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum>
       </citerefentry>
     </para>
   </refsect1>
diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml
index ace1dc63367..3a776b3f421 100644
--- a/man/systemd.netdev.xml
+++ b/man/systemd.netdev.xml
@@ -39,17 +39,22 @@
     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> and
+    <filename>/usr/local/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 alphanumeric order, regardless of the directories in which they live. However, files
+    with identical filenames replace each other. It is recommended that each filename is prefixed with
+    a number (e.g. <filename>10-vlan.netdev</filename>). Otherwise, <filename>.netdev</filename> files
+    generated by
+    <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    may take precedence over user configured files. 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>
@@ -2433,7 +2438,8 @@ Independent=yes</programlisting>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/systemd.network.xml b/man/systemd.network.xml
index daab872fdd3..4f1c9e4b27f 100644
--- a/man/systemd.network.xml
+++ b/man/systemd.network.xml
@@ -42,8 +42,12 @@
     <filename>/usr/local/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
+    processed in alphanumeric order, regardless of the directories in which they live. However, files
+    with identical filenames replace each other. It is recommended that each filename is prefixed with
+    a number (e.g. <filename>10-eth0.network</filename>). Otherwise, the default
+    <filename>.network</filename> files or those generated by
+    <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    may take precedence over user configured files. Files in <filename>/etc/</filename> have the highest
     priority, files in <filename>/run/</filename> take precedence over files with the same name under
     <filename>/usr/</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
@@ -69,9 +73,9 @@
     <title>[Match] Section Options</title>
 
     <para>The network file contains a [Match] section, which determines if a given network file may
-    be applied to a given device; and a [Network] section specifying how the device should be
-    configured. The first (in lexical order) of the network files that matches a given device is
-    applied, all later files are ignored, even if they match as well.</para>
+    be applied to a given interface; and a [Network] section specifying how the interface should be
+    configured. The first (in alphanumeric order) of the network files that matches a given interface
+    is applied, all later files are ignored, even if they match as well.</para>
 
     <para>A network file is said to match a network interface if all matches specified by the [Match]
     section are satisfied. When a network file does not contain valid settings in [Match] section, then
@@ -4774,6 +4778,7 @@ Xfrm=xfrm0</programlisting>
       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
   </refsect1>