From a50fa2a40f4a91d49503d3588a3dd29ea05e559b Mon Sep 17 00:00:00 2001
From: Tim Small <tim@seoss.co.uk>
Date: Fri, 2 May 2025 13:40:00 +0100
Subject: [PATCH] man/network: Note .link early boot caveat, and .network
 .netdev usage.

Document .link .network and .netdev file type distinctions in early
introductory text, and document distro-specific need to sync link files
with early-boot copies, see Debian bug 1005282:
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1005282 for an
example.
---
 man/systemd-networkd.service.xml | 24 ++++++++++++++----------
 man/systemd.link.xml             |  5 +++++
 man/systemd.network.xml          |  8 ++++++++
 3 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/man/systemd-networkd.service.xml b/man/systemd-networkd.service.xml
index 2ded90f0f3e..b3913004e86 100644
--- a/man/systemd-networkd.service.xml
+++ b/man/systemd-networkd.service.xml
@@ -33,12 +33,16 @@
     manages networks. It detects and configures network devices as
     they appear, as well as creating virtual network devices.</para>
 
-    <para>To configure low-level link settings independently of
-    networks, see
-    <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
-
-    <para><command>systemd-networkd</command> will create network devices based
-    on the configuration in
+    <para>Certain low-level settings of physical network devices (e.g. device
+    names and altnames) as well as the creation of SR-IOV virtual functions on
+    physical network interfaces may be managed by
+    <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    according to the contents of
+    <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    files.</para>
+
+    <para><command>systemd-networkd</command> will create "virtual" network
+    devices (e.g. bridges and tunnels) based on the configuration in
     <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     files, respecting the [Match] sections in those files.</para>
 
@@ -47,10 +51,10 @@
     with an appropriate [Match] section, see
     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     For those links, it will flush existing network addresses and routes when
-    bringing up the device. Any links not matched by one of the
-    <filename>.network</filename> files will be ignored. It is also possible to
-    explicitly tell <filename>systemd-networkd</filename> to ignore a link by
-    using <varname>Unmanaged=yes</varname> option, see
+    bringing up the device (except when directed not to). Any links not matched
+    by one of the <filename>.network</filename> files will be ignored. It is
+    also possible to explicitly tell <filename>systemd-networkd</filename> to
+    ignore a link by using the <varname>Unmanaged=yes</varname> option, see
     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     </para>
 
diff --git a/man/systemd.link.xml b/man/systemd.link.xml
index 86507d3e3ab..7643430549b 100644
--- a/man/systemd.link.xml
+++ b/man/systemd.link.xml
@@ -33,6 +33,11 @@
     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> for a
     general description of the syntax.</para>
 
+    <para>Note that some distributions may incorporate <filename>.link</filename> files in their early boot
+    facilities (e.g. by including copies of the <filename>.link</filename> files in initramfs). As such it
+    may be necessary to take manual steps to ensure that any local changes are consistent with early-boot
+    storage facilities. The relevant distribution-specific documentation should be consulted.</para>
+
     <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>
diff --git a/man/systemd.network.xml b/man/systemd.network.xml
index 98df365f1b7..3129c1e37d4 100644
--- a/man/systemd.network.xml
+++ b/man/systemd.network.xml
@@ -37,6 +37,14 @@
     <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>Note that not all settings and configurations can be made with <filename>.network</filename>
+    files, and that it may be necessary to use
+    <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+    or
+    <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+    files in conjuction with <filename>.network</filename> files when working with physical and virtual
+    network devices respectively.</para>
+
     <para>The <filename>.network</filename> files are read from the files located in the system network
     directories <filename>/usr/lib/systemd/network</filename> and
     <filename>/usr/local/lib/systemd/network</filename>
-- 
2.47.3