X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.special.xml;h=76bb5cdcf32e392eea245f4a2ba9b0d462657c4c;hp=a76e4cc94f6f156648f344d4604fc05d534a7a0b;hb=f58ceb21e9cdc4b79586283743351750ae35c175;hpb=54f874c56bebfaf199f84fca4bb2650a859bfac2

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index a76e4cc94..76bb5cdcf 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -71,6 +71,7 @@
                 <filename>local-fs-pre.target</filename>,
                 <filename>multi-user.target</filename>,
                 <filename>network.target</filename>,
+                <filename>network-online.target</filename>,
                 <filename>nss-lookup.target</filename>,
                 <filename>nss-user-lookup.target</filename>,
                 <filename>paths.target</filename>,
@@ -79,7 +80,6 @@
                 <filename>reboot.target</filename>,
                 <filename>remote-fs.target</filename>,
                 <filename>remote-fs-pre.target</filename>,
-                <filename>remote-fs-setup.target</filename>,
                 <filename>rescue.target</filename>,
                 <filename>initrd-root-fs.target</filename>,
                 <filename>rpcbind.target</filename>,
@@ -100,7 +100,11 @@
                 <filename>system-update.target</filename>,
                 <filename>time-sync.target</filename>,
                 <filename>timers.target</filename>,
-                <filename>umount.target</filename></para>
+                <filename>umount.target</filename>,
+                <filename>-.slice</filename>,
+                <filename>system.slice</filename>,
+                <filename>user.slice</filename>,
+                <filename>machine.slice</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
@@ -314,7 +318,7 @@
                                         dependencies of type
                                         <varname>Before=</varname> to
                                         <filename>sysroot-usr.mount</filename>
-                                        and all mount points fround in
+                                        and all mount points found in
                                         <filename>/etc/fstab</filename>
                                         that have the
                                         <option>auto</option> and
@@ -381,34 +385,72 @@
                                         this unit during
                                         installation. This is best
                                         configured via
-                                        <varname>WantedBy=multi-uer.target</varname>
+                                        <varname>WantedBy=multi-user.target</varname>
                                         in the unit's
                                         <literal>[Install]</literal>
                                         section.</para>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>network.target</filename></term>
+                                <term><filename>network-online.target</filename></term>
                                 <listitem>
-                                        <para>systemd automatically
-                                        adds dependencies of type
-                                        <varname>After=</varname> for
-                                        this target unit to all SysV
-                                        init script service units with
-                                        an LSB header referring to the
-                                        <literal>$network</literal>
-                                        facility.</para>
+                                        <para>Units that strictly
+                                        require a configured network
+                                        connection should pull in
+                                        <filename>network-online.target</filename>
+                                        (via a
+                                        <varname>Wants=</varname> type
+                                        dependency) and order
+                                        themselves after it. This
+                                        target unit is intended to
+                                        pull in a service that delays
+                                        further execution until the
+                                        network is sufficiently set
+                                        up. What precisely this
+                                        requires is left to the
+                                        implementation of the network
+                                        managing service.</para>
 
-                                        <para>This unit is supposed to
-                                        indicate when the network is
-                                        "up", but it is only very
-                                        loosely defined what that is
-                                        supposed to mean. Also see <ulink
+                                        <para>Note the distinction
+                                        between this unit and
+                                        <filename>network.target</filename>. This
+                                        unit is an active unit
+                                        (i.e. pulled in by the
+                                        consumer rather than the
+                                        provider of this
+                                        functionality) and pulls in a
+                                        service which possibly adds
+                                        substantial delays to further
+                                        execution. In contrast,
+                                        <filename>network.target</filename>
+                                        is a passive unit (i.e. pulled
+                                        in by the provider of the
+                                        functionality, rather than the
+                                        consumer) that usually does
+                                        not delay execution
+                                        much. Usually,
+                                        <filename>network.target</filename>
+                                        is part of the boot of most
+                                        systems, while
+                                        <filename>network-online.target</filename>
+                                        is not, except when at least
+                                        one unit requires it. Also see
+                                        <ulink
                                         url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
                                         Services After the Network is
                                         up</ulink> for more
                                         information.</para>
-                                </listitem>
+
+                                        <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>
+                                        </listitem>
                         </varlistentry>
                         <varlistentry>
                                 <term><filename>paths.target</filename></term>
@@ -481,29 +523,6 @@
                                         facility.</para>
                                 </listitem>
                         </varlistentry>
-                        <varlistentry>
-                                <term><filename>remote-fs-setup.target</filename></term>
-                                <listitem>
-                                        <para>This target unit is
-                                        automatically pulled in (by a
-                                        <varname>Wants=</varname> type
-                                        dependency) by all remote
-                                        mount points. It can be used
-                                        to run certain units when at
-                                        least one remote file system
-                                        is to be mounted. Note that
-                                        this target is not ordered
-                                        against the remote mounts, use
-                                        <filename>remote-fs-pre.target</filename>
-                                        for that (see below).</para>
-
-                                        <para>Again, this target unit
-                                        is <emphasis>not</emphasis>
-                                        suitable for ordering, it is
-                                        only useful for pulling in
-                                        other units.</para>
-                                </listitem>
-                        </varlistentry>
                         <varlistentry>
                                 <term><filename>rescue.target</filename></term>
                                 <listitem>
@@ -769,7 +788,7 @@
                                         available at boot.</para>
 
                                         <para>This may be used to pull
-                                        in printer management
+                                        in smartcard management
                                         daemons dynamically when
                                         smartcard hardware is
                                         found.</para>
@@ -786,7 +805,7 @@
 
                                         <para>This may be used to pull
                                         in audio management daemons
-                                        dynamically when printer
+                                        dynamically when audio
                                         hardware is found.</para>
                                 </listitem>
                         </varlistentry>
@@ -811,6 +830,14 @@
                 (via a <varname>Wants=</varname> type
                 dependency).</para>
 
+                <para>Note that these passive units cannot be started
+                manually, i.e. <literal>systemctl start
+                time-sync.target</literal> will fail with an
+                error. They can only be pulled in by dependency. This
+                is enforced since they exist for ordering purposes
+                only and thus are not useful as only unit within a
+                transaction.</para>
+
                 <variablelist>
                         <varlistentry>
                                 <term><filename>local-fs-pre.target</filename></term>
@@ -824,6 +851,40 @@
                                         all local mounts.</para>
                                 </listitem>
                         </varlistentry>
+                        <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. Also see <ulink
+                                        url="http://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>systemd automatically
+                                        adds dependencies of type
+                                        <varname>After=</varname> for
+                                        this target unit to all SysV
+                                        init script service units with
+                                        an LSB header referring to the
+                                        <literal>$network</literal>
+                                        facility.</para>
+
+                                </listitem>
+                        </varlistentry>
                         <varlistentry>
                                 <term><filename>nss-lookup.target</filename></term>
                                 <listitem>
@@ -878,9 +939,9 @@
                                         <varname>Wants=</varname> type
                                         dependency. If the unit wants
                                         to be pulled in by the first
-                                        remote mount showing up it
+                                        remote mount showing up, it
                                         should use
-                                        <filename>remote-fs-setup.target</filename>
+                                        <filename>network-online.target</filename>
                                         (see above).</para>
 
                                         <para>Again, this target unit
@@ -927,9 +988,15 @@
                 similar definitions as their system counterparts:
                 <filename>default.target</filename>,
                 <filename>shutdown.target</filename>,
-                <filename>sockets.target</filename></para>
+                <filename>sockets.target</filename>,
+                <filename>timers.target</filename>,
+                <filename>paths.target</filename>,
+                <filename>bluetooth.target</filename>,
+                <filename>printer.target</filename>,
+                <filename>smartcard.target</filename>,
+                <filename>sound.target</filename>.</para>
 
-                <para>In addition the following special unit is
+                <para>In addition, the following special unit is
                 understood only when systemd runs as service instance:</para>
 
                 <variablelist>
@@ -944,8 +1011,8 @@
                                         terminate the user service
                                         manager should start this
                                         unit. If systemd receives
-                                        SIGTERM or SIGINT when running
-                                        as user service daemon it will
+                                        <constant>SIGTERM</constant> or <constant>SIGINT</constant> when running
+                                        as user service daemon, it will
                                         start this unit.</para>
 
                                         <para>Normally, this pulls in
@@ -959,6 +1026,63 @@
                 </variablelist>
         </refsect1>
 
+        <refsect1>
+                <title>Special Slice Units</title>
+
+                <para>There are four <literal>.slice</literal> units
+                which form the basis of the hierarchy for assignment
+                of resources for services, users, and virtual machines
+                or containers.</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><filename>-.slice</filename></term>
+                                <listitem>
+                                        <para>The root slice is the
+                                        root of the hierarchy. It
+                                        usually does not contain units
+                                        directly, but may be used to
+                                        set defaults for the whole
+                                        tree.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><filename>system.slice</filename></term>
+                                <listitem>
+                                        <para>By default, all services
+                                        services started by
+                                        <command>systemd</command> are
+                                        found in this slice.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><filename>user.slice</filename></term>
+                                <listitem>
+                                        <para>By default, all user
+                                        processes and services started
+                                        on behalf of the user,
+                                        including the per-user systemd
+                                        instance are found in this
+                                        slice.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><filename>machine.slice</filename></term>
+                                <listitem>
+                                        <para>By defalt, all virtual
+                                        machines and containers
+                                        registered with
+                                        <command>systemd-machined</command>
+                                        are found in this slice.
+                                        </para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+        </refsect1>
+
         <refsect1>
                   <title>See Also</title>
                   <para>
@@ -967,6 +1091,7 @@
                           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                   </para>