man: bring machinectl man page up-to-date

[elogind.git] / man / systemd.special.xml

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index d1cd81f1d1137438ef76361bc0cc1af706ded780..863d7f35d924b8c383c3ef59de63021b554c77fd 100644 (file)
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -52,6 +52,7 @@
                 <filename>bluetooth.target</filename>,
                 <filename>ctrl-alt-del.target</filename>,
                 <filename>cryptsetup.target</filename>,
                 <filename>bluetooth.target</filename>,
                 <filename>ctrl-alt-del.target</filename>,
                 <filename>cryptsetup.target</filename>,

+                <filename>cryptsetup-pre.target</filename>,

                 <filename>dbus.service</filename>,
                 <filename>dbus.socket</filename>,
                 <filename>default.target</filename>,
                 <filename>dbus.service</filename>,
                 <filename>dbus.socket</filename>,
                 <filename>default.target</filename>,


@@ -72,6 +73,7 @@
                 <filename>multi-user.target</filename>,
                 <filename>network.target</filename>,
                 <filename>network-online.target</filename>,
                 <filename>multi-user.target</filename>,
                 <filename>network.target</filename>,
                 <filename>network-online.target</filename>,

+                <filename>network-pre.target</filename>,

                 <filename>nss-lookup.target</filename>,
                 <filename>nss-user-lookup.target</filename>,
                 <filename>paths.target</filename>,
                 <filename>nss-lookup.target</filename>,
                 <filename>nss-user-lookup.target</filename>,
                 <filename>paths.target</filename>,


@@ -100,7 +102,11 @@
                 <filename>system-update.target</filename>,
                 <filename>time-sync.target</filename>,
                 <filename>timers.target</filename>,
                 <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>
         </refsynopsisdiv>
 
         <refsect1>


@@ -316,11 +322,10 @@
                                         <filename>sysroot-usr.mount</filename>
                                         and all mount points found in
                                         <filename>/etc/fstab</filename>
                                         <filename>sysroot-usr.mount</filename>
                                         and all mount points found in
                                         <filename>/etc/fstab</filename>

-                                        that have the
-                                        <option>auto</option> and
+                                        that have

                                         <option>x-initrd.mount</option>
                                         <option>x-initrd.mount</option>

-                                        mount options set.
-                                        </para>
+                                        and not have <option>noauto</option>
+                                        mount options set.</para>

                                 </listitem>
                         </varlistentry>
                         <varlistentry>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -381,7 +386,7 @@
                                         this unit during
                                         installation. This is best
                                         configured via
                                         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>
                                         in the unit's
                                         <literal>[Install]</literal>
                                         section.</para>


@@ -444,7 +449,7 @@
                                         after it. Note that networking
                                         daemons that simply provide
                                         functionality to other hosts
                                         after it. Note that networking
                                         daemons that simply provide
                                         functionality to other hosts

-                                        generally don't need to pull
+                                        generally do not need to pull

                                         this in.</para>
                                         </listitem>
                         </varlistentry>
                                         this in.</para>
                                         </listitem>
                         </varlistentry>


@@ -816,7 +821,7 @@
                 services. These targets are generally not part of the
                 initial boot transaction, unless they are explicitly
                 pulled in by one of the implementing services. Note
                 services. These targets are generally not part of the
                 initial boot transaction, unless they are explicitly
                 pulled in by one of the implementing services. Note

-                specifically, that these <emphasis>passive</emphasis>
+                specifically that these <emphasis>passive</emphasis>

                 target units are generally not pulled in by the
                 consumer of a service, but by the provider of the
                 service. This means: a consuming service should order
                 target units are generally not pulled in by the
                 consumer of a service, but by the provider of the
                 service. This means: a consuming service should order


@@ -835,6 +840,27 @@
                 transaction.</para>
 
                 <variablelist>
                 transaction.</para>
 
                 <variablelist>

+                        <varlistentry>
+                                <term><filename>cryptsetup-pre.target</filename></term>
+                                <listitem>
+                                        <para>This passive target unit
+                                        may be pulled in by services
+                                        that want to run before any
+                                        encrypted block device is set
+                                        up. All encrypted block
+                                        devices are set up after this
+                                        target has been reached. Since
+                                        the shutdown order is
+                                        implicitly the reverse
+                                        start-up order between units,
+                                        this target is particularly
+                                        useful to ensure that a
+                                        service is shut down only
+                                        after all encrypted block
+                                        devices are fully
+                                        stopped.</para>
+                                </listitem>
+                        </varlistentry>

                         <varlistentry>
                                 <term><filename>local-fs-pre.target</filename></term>
                                 <listitem>
                         <varlistentry>
                                 <term><filename>local-fs-pre.target</filename></term>
                                 <listitem>


@@ -862,7 +888,13 @@
                                         will be stopped before the
                                         network -- to whatever level
                                         it might be set up then -- is
                                         will be stopped before the
                                         network -- to whatever level
                                         it might be set up then -- is

-                                        shut down. Also see <ulink
+                                        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="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
                                         Services After the Network is
                                         up</ulink> for more
                                         url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
                                         Services After the Network is
                                         up</ulink> for more


@@ -878,7 +910,20 @@
                                         an LSB header referring to the
                                         <literal>$network</literal>
                                         facility.</para>
                                         an LSB header referring to the
                                         <literal>$network</literal>
                                         facility.</para>

-
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>network-pre.target</filename></term>
+                                <listitem>
+                                        <para>This passive target unit
+                                        may be pulled in by services
+                                        that want to run before any
+                                        network is set up, for example
+                                        for the purpose of setting up a
+                                        firewall. All network
+                                        management software orders
+                                        itself after this target, but
+                                        does not pull it in.</para>

                                 </listitem>
                         </varlistentry>
                         <varlistentry>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -892,7 +937,12 @@
                                         user/group name lookups for
                                         which
                                         <filename>nss-user-lookup.target</filename>
                                         user/group name lookups for
                                         which
                                         <filename>nss-user-lookup.target</filename>

-                                        should be used. systemd
+                                        should be used. All services
+                                        for which the availability of
+                                        full host/network name
+                                        resolution is essential should
+                                        be ordered after this target,
+                                        but not pull it in. systemd

                                         automatically adds
                                         dependencies of type
                                         <varname>After=</varname> for
                                         automatically adds
                                         dependencies of type
                                         <varname>After=</varname> for


@@ -914,7 +964,16 @@
                                         host/network name lookups for
                                         which
                                         <filename>nss-lookup.target</filename>
                                         host/network name lookups for
                                         which
                                         <filename>nss-lookup.target</filename>

-                                        should be used. </para>
+                                        should be used. All services
+                                        for which the availability of
+                                        the full user/group database is
+                                        essential should be ordered
+                                        after this target, but not
+                                        pull it in. Note that system
+                                        users are always resolvable,
+                                        and hence do not require any
+                                        special ordering against this
+                                        target.</para>

                                 </listitem>
                         </varlistentry>
                         <varlistentry>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -935,23 +994,22 @@
                                         <varname>Wants=</varname> type
                                         dependency. If the unit wants
                                         to be pulled in by the first
                                         <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>network-online.target</filename>
                                         (see above).</para>
                                         should use
                                         <filename>network-online.target</filename>
                                         (see above).</para>

-
-                                        <para>Again, this target unit
-                                        is <emphasis>not</emphasis>
-                                        suitable for pulling in other
-                                        units, it is only useful for
-                                        ordering.</para>

                                 </listitem>
                         </varlistentry>
                         <varlistentry>
                                 <term><filename>rpcbind.target</filename></term>
                                 <listitem>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
                                 <term><filename>rpcbind.target</filename></term>
                                 <listitem>

-                                        <para>systemd automatically
-                                        adds dependencies of type
+                                        <para>The portmapper/rpcbind
+                                        pulls in this target and
+                                        orders itself before it, to
+                                        indicate its
+                                        availability. systemd
+                                        automatically adds
+                                        dependencies of type

                                         <varname>After=</varname> for
                                         this target unit to all SysV
                                         init script service units with
                                         <varname>After=</varname> for
                                         this target unit to all SysV
                                         init script service units with


@@ -963,14 +1021,24 @@
                         <varlistentry>
                                 <term><filename>time-sync.target</filename></term>
                                 <listitem>
                         <varlistentry>
                                 <term><filename>time-sync.target</filename></term>
                                 <listitem>

-                                        <para>systemd automatically
-                                        adds dependencies of type
+                                        <para>Services responsible for
+                                        synchronizing the system clock
+                                        from a remote source (such as
+                                        NTP client implementations)
+                                        should pull in this target and
+                                        order themselves before
+                                        it. All services where correct
+                                        time is essential should be
+                                        ordered after this unit, but
+                                        not pull it in. 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>$time</literal>
                                         <varname>After=</varname> for
                                         this target unit to all SysV
                                         init script service units with
                                         an LSB header referring to the
                                         <literal>$time</literal>

-                                        facility.</para>
+                                        facility. </para>

                                 </listitem>
                         </varlistentry>
                 </variablelist>
                                 </listitem>
                         </varlistentry>
                 </variablelist>


@@ -992,7 +1060,7 @@
                 <filename>smartcard.target</filename>,
                 <filename>sound.target</filename>.</para>
 
                 <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>
                 understood only when systemd runs as service instance:</para>
 
                 <variablelist>


@@ -1008,7 +1076,7 @@
                                         manager should start this
                                         unit. If systemd receives
                                         <constant>SIGTERM</constant> or <constant>SIGINT</constant> when running
                                         manager should start this
                                         unit. If systemd receives
                                         <constant>SIGTERM</constant> or <constant>SIGINT</constant> when running

-                                        as user service daemon it will
+                                        as user service daemon, it will

                                         start this unit.</para>
 
                                         <para>Normally, this pulls in
                                         start this unit.</para>
 
                                         <para>Normally, this pulls in


@@ -1022,6 +1090,63 @@
                 </variablelist>
         </refsect1>
 
                 </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 default, 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>
         <refsect1>
                   <title>See Also</title>
                   <para>


@@ -1030,7 +1155,8 @@
                           <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.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>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                   </para>
         </refsect1>
                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                   </para>
         </refsect1>