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 6d456e18e52625be0504336713bf1188ae2e201d..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>,


@@ -320,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>


@@ -385,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>


@@ -448,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>


@@ -820,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


@@ -839,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>


@@ -866,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


@@ -882,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>


@@ -896,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


@@ -918,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>


@@ -939,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


@@ -967,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>


@@ -996,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>


@@ -1012,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


@@ -1050,7 +1114,7 @@
                         <varlistentry>
                                 <term><filename>system.slice</filename></term>
                                 <listitem>
                         <varlistentry>
                                 <term><filename>system.slice</filename></term>
                                 <listitem>

-                                        <para>By default all services
+                                        <para>By default, all services

                                         services started by
                                         <command>systemd</command> are
                                         found in this slice.</para>
                                         services started by
                                         <command>systemd</command> are
                                         found in this slice.</para>


@@ -1060,7 +1124,7 @@
                         <varlistentry>
                                 <term><filename>user.slice</filename></term>
                                 <listitem>
                         <varlistentry>
                                 <term><filename>user.slice</filename></term>
                                 <listitem>

-                                        <para>By default all user
+                                        <para>By default, all user

                                         processes and services started
                                         on behalf of the user,
                                         including the per-user systemd
                                         processes and services started
                                         on behalf of the user,
                                         including the per-user systemd


@@ -1072,7 +1136,7 @@
                         <varlistentry>
                                 <term><filename>machine.slice</filename></term>
                                 <listitem>
                         <varlistentry>
                                 <term><filename>machine.slice</filename></term>
                                 <listitem>

-                                        <para>By defalt all virtual
+                                        <para>By default, all virtual

                                         machines and containers
                                         registered with
                                         <command>systemd-machined</command>
                                         machines and containers
                                         registered with
                                         <command>systemd-machined</command>


@@ -1092,7 +1156,7 @@
                           <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>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 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>