Merge pull request #18800 from poettering/network-target-more-doc

some improvements regarding network.target docs

1 files changed, 34 insertions, 26 deletions

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 948380b9b5..c9f320935d 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -489,11 +489,10 @@
             Services After the Network is up</ulink> for more
             information.</para>
 
-            <para>All mount units for remote network file systems
-            automatically pull in this unit, and order themselves after
-            it. Note that networking daemons that simply provide
-            functionality to other hosts generally do not need to pull
-            this in.</para>
+            <para>All mount units for remote network file systems automatically pull in this unit, and order
+            themselves after it. Note that networking daemons that simply <emphasis>provide</emphasis>
+            functionality to other hosts (as opposed to <emphasis>consume</emphasis> functionality of other
+            hosts) generally do not need to pull this in.</para>
 
             <para>systemd automatically adds dependencies of type <varname>Wants=</varname> and
             <varname>After=</varname> for this target unit to all SysV init script service units
@@ -949,20 +948,29 @@
         <varlistentry>
           <term><filename>network.target</filename></term>
           <listitem>
-            <para>This unit is supposed to indicate when network
-            functionality is available, but it is only very weakly
-            defined what that is supposed to mean, with one exception:
-            at shutdown, a unit that is ordered after
-            <filename>network.target</filename> will be stopped before
-            the network — to whatever level it might be set up then —
-            is shut down. It is hence useful when writing service files
-            that require network access on shutdown, which should order
-            themselves after this target, but not pull it in. Also see
-            <ulink url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
-            Services After the Network is up</ulink> for more
-            information. Also see
-            <filename>network-online.target</filename> described
-            above.</para>
+            <para>This unit is supposed to indicate when network functionality is available, but it is only
+            very weakly defined what that is supposed to mean. However, the following should apply at
+            minimum:</para>
+
+            <itemizedlist>
+              <listitem><para>At start-up, any configured synthetic network devices (i.e. not physical ones
+              that require hardware to show up and be probed, but virtual ones like bridge devices and
+              similar which are created programmatically) that do not depend on any underlying hardware
+              should be allocated by the time this target is reached. It is not necessary for these
+              interfaces to also have completed IP level configuration by the time
+              <filename>network.target</filename> is reached.</para></listitem>
+
+              <listitem><para>At shutdown, a unit that is ordered after <filename>network.target</filename>
+              will be stopped before the network — to whatever level it might be set up by then — is shut
+              down. It is hence useful when writing service files that require network access on shutdown,
+              which should order themselves after this target, but not pull it in. Also see <ulink
+              url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running Services After
+              the Network is up</ulink> for more information.</para></listitem>
+            </itemizedlist>
+
+            <para>It must emphasized that at start-up there's no guarantee that hardware-based devices have
+            shown up by the time this target is reached, or even acquired complete IP configuration. For that
+            purpose use <filename>network-online.target</filename> as described above.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
@@ -1247,18 +1255,18 @@
               <para><literal>gnome-session.target</literal> pulls in Nautilus as top-level service:</para>
 
               <programlisting>[Unit]
-  Description=User systemd services for GNOME graphical session
-  Wants=nautilus.service
-  BindsTo=graphical-session.target</programlisting>
+Description=User systemd services for GNOME graphical session
+Wants=nautilus.service
+BindsTo=graphical-session.target</programlisting>
 
               <para><literal>nautilus.service</literal> gets stopped when the session stops:</para>
 
               <programlisting>[Unit]
-  Description=Render the desktop icons with Nautilus
-  PartOf=graphical-session.target
+Description=Render the desktop icons with Nautilus
+PartOf=graphical-session.target
 
-  [Service]
-  …</programlisting>
+[Service]
+…</programlisting>
             </example>
           </listitem>
         </varlistentry>