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.

(cherry picked from commit a50fa2a40f4a91d49503d3588a3dd29ea05e559b)
(cherry picked from commit 1f654739f8a05110b68461cf483d5c07b2ef7723)

diff --git a/man/systemd-networkd.service.xml b/man/systemd-networkd.service.xml
index 2ded90f0f3ed4a5580c5fa0c654d8dec8dd8e2b2..b3913004e8670823d4a9fd7b06037f0df0eb1ba9 100644 (file)
--- 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 146d857bf43a8382ea10a334f4e567cf3eaeb5ff..4f8a49cf4c343505416ed4caa7e507ded955a2cc 100644 (file)
--- 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 29521ff46335e9f6c8578442763a8273c89721b6..233605765955bb08956ca19e84630a53395ec036 100644 (file)
--- 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>