man: complete service.special(7) man page

1 files changed, 326 insertions, 47 deletions

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 3f9286d4b..e81e99e44 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -48,22 +48,38 @@
         </refnamediv>
 
         <refsynopsisdiv>
+                <para><filename>basic.target</filename></para>
+                <para><filename>ctrl-alt-del.target</filename></para>
+                <para><filename>default.target</filename></para>
                 <para><filename>emergency.service</filename></para>
+                <para><filename>graphical.target</filename></para>
+                <para><filename>halt.target</filename></para>
+                <para><filename>kbrequest.target</filename></para>
                 <para><filename>local-fs.target</filename></para>
+                <para><filename>multi-user.target</filename></para>
                 <para><filename>network.target</filename></para>
                 <para><filename>nss-lookup.target</filename></para>
+                <para><filename>poweroff.target</filename></para>
+                <para><filename>reboot.target</filename></para>
                 <para><filename>remote-fs.target</filename></para>
+                <para><filename>rescue.target</filename></para>
                 <para><filename>rpcbind.target</filename></para>
                 <para><filename>rtc-set.target</filename></para>
+                <para><filename>runlevel0.target</filename>,
+                        <filename>runlevel0.target</filename>,
+                        <filename>runlevel1.target</filename>,
+                        <filename>runlevel2.target</filename>,
+                        <filename>runlevel3.target</filename>,
+                        <filename>runlevel4.target</filename>,
+                        <filename>runlevel5.target</filename>,
+                        <filename>runlevel6.target</filename></para>
                 <para><filename>shutdown.target</filename></para>
                 <para><filename>sigpwr.target</filename></para>
                 <para><filename>sockets.target</filename></para>
                 <para><filename>swap.target</filename></para>
                 <para><filename>syslog.target</filename></para>
-                <para><filename>systemd-initctl.service</filename></para>
-                <para><filename>systemd-initctl.socket</filename></para>
-                <para><filename>systemd-logger.service</filename></para>
-                <para><filename>systemd-logger.socket</filename></para>
+                <para><filename>systemd-initctl.service</filename>, <filename>systemd-initctl.socket</filename></para>
+                <para><filename>systemd-logger.service</filename>, <filename>systemd-logger.socket</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
@@ -79,6 +95,58 @@
 
                 <variablelist>
                         <varlistentry>
+                                <term><filename>basic.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        covering early boot-up.</para>
+                                        <para>systemd automatically
+                                        adds dependencies of the types
+                                        Requires and After for this
+                                        target unit to all SysV
+                                        service units configured for
+                                        runlevel 1 to 5.</para>
+                                        <para>systemd automatically
+                                        adds dependencies of the types
+                                        Wants and After for all
+                                        SysV service units configured
+                                        for runlevels that are not 0
+                                        to 6 to this target unit.
+                                        This covers the special
+                                        boot-up runlevels some
+                                        distributions have, such as S
+                                        or b.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>ctrl-alt-del.target</filename></term>
+                                <listitem>
+                                        <para>systemd starts this
+                                        target whenever
+                                        Control+Alt+Del is pressed on
+                                        the console. Usually this
+                                        should be aliased (symlinked)
+                                        to
+                                        <filename>reboot.target</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>default.target</filename></term>
+                                <listitem>
+                                        <para>The default unit systemd
+                                        starts at bootup. Usually this
+                                        should be aliased (symlinked)
+                                        to
+                                        <filename>multi-user.target</filename>
+                                        or
+                                        <filename>graphical.target</filename>.</para>
+                                        <para>The default unit systemd
+                                        starts at bootup can be
+                                        overriden with the
+                                        <varname>systemd.default=</varname>
+                                        kernel command line option.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
                                 <term><filename>emergency.service</filename></term>
                                 <listitem>
                                         <para>A special service unit
@@ -93,16 +161,55 @@
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
+                                <term><filename>graphical.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        for setting up a graphical
+                                        login screen. This pulls in
+                                        <filename>multi-user.target</filename>.</para>
+
+                                        <para>Units that are needed
+                                        for graphical login shall add
+                                        Wants dependencies for their
+                                        unit to this unit (or
+                                        <filename>multi-user.target</filename>)
+                                        during installation.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>halt.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        for shutting down and halting the system.</para>
+
+                                        <para>Applications wanting to
+                                        halt the system should start
+                                        this unit.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>kbrequest.target</filename></term>
+                                <listitem>
+                                        <para>systemd starts this
+                                        target whenever Alt+ArrowUp is
+                                        pressed on the console. This
+                                        is a good candidate to be
+                                        aliased (symlinked) to
+                                        <filename>rescue.target</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
                                 <term><filename>local-fs.target</filename></term>
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
                                         After to all mount units that
-                                        refer to local mount
-                                        points. In addition, systemd
-                                        adds dependencies of type
-                                        Wants to those mounts listed
-                                        in
+                                        refer to local mount points
+                                        for this target unit. In
+                                        addition, systemd adds
+                                        dependencies of type Wants to
+                                        this target unit for those
+                                        mounts listed in
                                         <filename>/etc/fstab</filename>
                                         that have the
                                         <literal>auto</literal> and
@@ -111,21 +218,39 @@
 
                                         <para>systemd automatically
                                         adds dependencies of type
-                                        After to this target unit for
-                                        all SysV init scripts with an
-                                        LSB header referring to the
+                                        After for this target unit to
+                                        all SysV init script service
+                                        units with an LSB header
+                                        referring to the
                                         <literal>$local_fs</literal>
                                         facility.</para>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
+                                <term><filename>multi-user.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        for setting up a multi-user
+                                        system (non-graphical). This
+                                        is pulled in by
+                                        <filename>graphical.target</filename>.</para>
+
+                                        <para>Units that are needed
+                                        for a multi-user system shall
+                                        add Wants dependencies to
+                                        this unit for their unit during
+                                        installation.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
                                 <term><filename>network.target</filename></term>
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
-                                        After to this target unit for
-                                        all SysV init scripts with an
-                                        LSB header referring to the
+                                        After for this target unit to
+                                        all SysV init script service
+                                        units with an LSB header
+                                        referring to the
                                         <literal>$network</literal>
                                         facility.</para>
                                 </listitem>
@@ -135,34 +260,83 @@
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
-                                        After to this target unit for
-                                        all SysV init scripts with an
-                                        LSB header referring to the
+                                        After for this target unit to
+                                        all SysV init script service
+                                        units with an LSB header
+                                        referring to the
                                         <literal>$named</literal>
                                         facility.</para>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
+                                <term><filename>poweroff.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        for shutting down and powering off the system.</para>
+
+                                        <para>Applications wanting to
+                                        power off the system should start
+                                        this unit.</para>
+
+                                        <para><filename>runlevel0.target</filename>
+                                        is an alias for this target
+                                        unit, for compatibility with SysV.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>reboot.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        for shutting down and rebooting the system.</para>
+
+                                        <para>Applications wanting to
+                                        reboot the system should start
+                                        this unit.</para>
+
+                                        <para><filename>runlevel6.target</filename>
+                                        is an alias for this target
+                                        unit, for compatibility with SysV.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
                                 <term><filename>remote-fs.target</filename></term>
                                 <listitem>
-                                        <para>Similar to <filename>local-fs.target</filename>, but for remote mount points.</para>
+                                        <para>Similar to
+                                        <filename>local-fs.target</filename>,
+                                        but for remote mount
+                                        points.</para>
+
                                         <para>systemd automatically
                                         adds dependencies of type
-                                        After to this target unit for
-                                        all SysV init scripts with an
-                                        LSB header referring to the
+                                        After for this target unit to
+                                        all SysV init script service
+                                        units with an LSB header
+                                        referring to the
                                         <literal>$remote-fs</literal>
                                         facility.</para>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
+                                <term><filename>rescue.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        for setting up the base system
+                                        and a rescue shell.</para>
+
+                                        <para><filename>runlevel1.target</filename>
+                                        is an alias for this target
+                                        unit, for compatibility with SysV.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
                                 <term><filename>rpcbind.target</filename></term>
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
-                                        After to this target unit for
-                                        all SysV init scripts with an
-                                        LSB header referring to the
+                                        After for this target unit to
+                                        all SysV init script service
+                                        units with an LSB header
+                                        referring to the
                                         <literal>$rpcbind</literal>
                                         facility.</para>
                                 </listitem>
@@ -172,14 +346,108 @@
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
-                                        After to this target unit for
-                                        all SysV init scripts with an
-                                        LSB header referring to the
+                                        After for this target unit to
+                                        all SysV init script service
+                                        units with an LSB header
+                                        referring to the
                                         <literal>$time</literal>
                                         facility.</para>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
+                                <term><filename>runlevel0.target</filename></term>
+                                <listitem>
+                                        <para>This is a target that is
+                                        called whever the SysV
+                                        compatibility code asks for
+                                        runlevel 0. This is an alias
+                                        for
+                                        <filename>poweroff.target</filename>,
+                                        for compatibility with
+                                        SysV.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>runlevel1.target</filename></term>
+                                <listitem>
+                                        <para>This is a target that is
+                                        called whever the SysV
+                                        compatibility code asks for
+                                        runlevel 1. This is an alias
+                                        for
+                                        <filename>rescue.target</filename>,
+                                        for compatibility with
+                                        SysV.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>runlevel2.target</filename></term>
+                                <listitem>
+                                        <para>This is a target that is
+                                        called whever the SysV
+                                        compatibility code asks for
+                                        runlevel 2. It is a good idea
+                                        to make this an alias for
+                                        (i.e. symlink to)
+                                        <filename>multi-user.target</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>runlevel3.target</filename></term>
+                                <listitem>
+                                        <para>This is a target that is
+                                        called whever the SysV
+                                        compatibility code asks for
+                                        runlevel 3. It is a good idea
+                                        to make this an alias for
+                                        (i.e. symlink to)
+                                        <filename>multi-user.target</filename>
+                                        or
+                                        <filename>graphical.target</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>runlevel4.target</filename></term>
+                                <listitem>
+                                        <para>This is a target that is
+                                        called whever the SysV
+                                        compatibility code asks for
+                                        runlevel 4. It is a good idea
+                                        to make this an alias for
+                                        (i.e. symlink to)
+                                        <filename>multi-user.target</filename>
+                                        or
+                                        <filename>graphical.target</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>runlevel5.target</filename></term>
+                                <listitem>
+                                        <para>This is a target that is
+                                        called whever the SysV
+                                        compatibility code asks for
+                                        runlevel 5. It is a good idea
+                                        to make this an alias for
+                                        (i.e. symlink to)
+                                        <filename>multi-user.target</filename>
+                                        or
+                                        <filename>graphical.target</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>runlevel6.target</filename></term>
+                                <listitem>
+                                        <para>This is a target that is
+                                        called whever the SysV
+                                        compatibility code asks for
+                                        runlevel 6. This is an alias
+                                        for
+                                        <filename>reboot.target</filename>,
+                                        for compatibility with
+                                        SysV.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
                                 <term><filename>shutdown.target</filename></term>
                                 <listitem>
                                         <para>A special target unit
@@ -188,17 +456,18 @@
 
                                         <para>Services that shall be
                                         terminated on system shutdown
-                                        shall add Wants dependencies
-                                        from this unit to their
-                                        service unit during
+                                        shall add Conflicts
+                                        dependencies to this unit for
+                                        their service unit during
                                         installation.</para>
 
                                         <para>systemd automatically
                                         adds dependencies of type
                                         Conflicts to this target unit
-                                        for all SysV init scripts that
-                                        shall be terminated in SysV
-                                        runlevels 0 or 6.</para>
+                                        for all SysV init script
+                                        service units that shall be
+                                        terminated in SysV runlevels 0
+                                        or 6.</para>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
@@ -208,7 +477,7 @@
                                         started when systemd receives
                                         the SIGPWR process signal,
                                         which is normally sent by the
-                                        kernel or UPS daemons when the
+                                        kernel or UPS daemons when
                                         power fails.</para>
                                 </listitem>
                         </varlistentry>
@@ -221,8 +490,8 @@
 
                                         <para>Services that can be
                                         socket-activated shall add
-                                        Wants dependencies from this
-                                        unit to their socket unit
+                                        Wants dependencies to this
+                                        unit for their socket unit
                                         during installation.</para>
                                 </listitem>
                         </varlistentry>
@@ -240,9 +509,10 @@
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
-                                        After to this target unit for
-                                        all SysV init scripts with an
-                                        LSB header referring to the
+                                        After for this target unit to
+                                        all SysV init script service
+                                        units with an LSB header
+                                        referring to the
                                         <literal>$syslog</literal>
                                         facility.</para>
 
@@ -250,9 +520,10 @@
                                         ensure that this target pulls
                                         in a service unit with the
                                         name or alias of
-                                        <filename>@SPECIAL_SYSLOG_NAME@</filename> (or a
-                                        socket unit that activates
-                                        this service).</para>
+                                        <filename>@SPECIAL_SYSLOG_SERVICE@</filename>
+                                        (or a socket unit that
+                                        activates this
+                                        service).</para>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
@@ -279,10 +550,10 @@
                         <varlistentry>
                                 <term><filename>systemd-logger.service</filename></term>
                                 <listitem>
-                                        <para>This is used internally
+                                        <para>This is internally used
                                         by systemd to provide syslog
-                                        logging to started
-                                        processes.</para>
+                                        logging to the processes it
+                                        maintains.</para>
                                         <para>This is a
                                         socket-activated service, see
                                         <filename>system-logger.socket</filename>.</para>
@@ -293,7 +564,14 @@
                                 <listitem>
                                         <para>Socket activation unit
                                         for
-                                        <filename>system-logger.service</filename>.</para>
+                                        <filename>system-logger.service</filename>. systemd
+                                        will automatically add
+                                        dependencies of types Requires
+                                        and After to all units that
+                                        have been configured for
+                                        stdout or stderr to be
+                                        connected to syslog or the
+                                        kernel log buffer.</para>
                                 </listitem>
                         </varlistentry>
                 </variablelist>
@@ -305,6 +583,7 @@
                 <para>When systemd runs as a service instance, the
                 following special units are available, which have
                 similar definitions as their system counterparts:
+                <filename>default.target</filename>,
                 <filename>local-fs.target</filename>,
                 <filename>remote-fs.target</filename>,
                 <filename>shutdown.target</filename>,