chiark / gitweb /
man: document a few special units
authorLennart Poettering <lennart@poettering.net>
Sun, 16 May 2010 20:45:11 +0000 (22:45 +0200)
committerLennart Poettering <lennart@poettering.net>
Sun, 16 May 2010 20:45:11 +0000 (22:45 +0200)
20 files changed:
.gitignore
Makefile.am
man/systemd.special.xml [new file with mode: 0644]
man/systemd.unit.xml
src/manager.h
units/emergency.service
units/local-fs.target
units/network.target
units/nss-lookup.target
units/remote-fs.target
units/rtc-set.target
units/shutdown.target
units/sigpwr.target
units/sockets.target
units/swap.target
units/syslog.target.in
units/systemd-initctl.service.in
units/systemd-initctl.socket
units/systemd-logger.service.in
units/systemd-logger.socket

index 4efd824..700a085 100644 (file)
@@ -10,6 +10,7 @@ systemctl
 systemadm
 .dirstamp
 *.5
 systemadm
 .dirstamp
 *.5
+*.7
 *.html
 *~
 *.tar.gz
 *.html
 *~
 *.tar.gz
index 780ded6..15da7b2 100644 (file)
@@ -156,18 +156,21 @@ EXTRA_DIST += \
 
 dist_man_MANS = \
        man/systemd.unit.5 \
 
 dist_man_MANS = \
        man/systemd.unit.5 \
-       man/systemd.service.5
+       man/systemd.service.5 \
+       man/systemd.special.7
 
 HTMLMANS = \
        man/systemd.unit.html \
 
 HTMLMANS = \
        man/systemd.unit.html \
-       man/systemd.service.html
+       man/systemd.service.html \
+       man/systemd.special.html
 
 dist_noinst_DATA = \
        $(HTMLMANS)
 
 EXTRA_DIST += \
        man/systemd.unit.xml \
 
 dist_noinst_DATA = \
        $(HTMLMANS)
 
 EXTRA_DIST += \
        man/systemd.unit.xml \
-       man/systemd.service.xml
+       man/systemd.service.xml \
+       man/systemd.special.xml
 
 systemd_SOURCES = \
        $(COMMON_SOURCES) \
 
 systemd_SOURCES = \
        $(COMMON_SOURCES) \
@@ -297,7 +300,7 @@ CLEANFILES = \
        units/syslog.target
 
 if HAVE_XSLTPROC
        units/syslog.target
 
 if HAVE_XSLTPROC
-man/%.5: man/%.xml
+man/%.5 man/%.7: man/%.xml
        $(MKDIR_P) man
        $(XSLTPROC) -o $@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
 
        $(MKDIR_P) man
        $(XSLTPROC) -o $@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
 
diff --git a/man/systemd.special.xml b/man/systemd.special.xml
new file mode 100644 (file)
index 0000000..3f9286d
--- /dev/null
@@ -0,0 +1,325 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2010 Lennart Poettering
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="systemd.special">
+
+        <refentryinfo>
+                <title>systemd.special</title>
+                <productname>systemd</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>Lennart</firstname>
+                                <surname>Poettering</surname>
+                                <email>lennart@poettering.net</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>systemd.special</refentrytitle>
+                <manvolnum>7</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>systemd.special</refname>
+                <refpurpose>special systemd units</refpurpose>
+        </refnamediv>
+
+        <refsynopsisdiv>
+                <para><filename>emergency.service</filename></para>
+                <para><filename>local-fs.target</filename></para>
+                <para><filename>network.target</filename></para>
+                <para><filename>nss-lookup.target</filename></para>
+                <para><filename>remote-fs.target</filename></para>
+                <para><filename>rpcbind.target</filename></para>
+                <para><filename>rtc-set.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>
+        </refsynopsisdiv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>A few units are treated specially by
+                systemd. They have special internal semantics and
+                cannot be renamed.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Special System Units</title>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><filename>emergency.service</filename></term>
+                                <listitem>
+                                        <para>A special service unit
+                                        that starts an emergency
+                                        shell on the main
+                                        console. This unit is supposed
+                                        to be used with the kernel
+                                        command line option
+                                        <varname>systemd.default=</varname>
+                                        and has otherwise little use.
+                                        </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
+                                        <filename>/etc/fstab</filename>
+                                        that have the
+                                        <literal>auto</literal> and
+                                        <literal>comment=systemd.mount</literal>
+                                        mount options set.</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
+                                        <literal>$local_fs</literal>
+                                        facility.</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
+                                        <literal>$network</literal>
+                                        facility.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>nss-lookup.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
+                                        <literal>$named</literal>
+                                        facility.</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>systemd automatically
+                                        adds dependencies of type
+                                        After to this target unit for
+                                        all SysV init scripts with an
+                                        LSB header referring to the
+                                        <literal>$remote-fs</literal>
+                                        facility.</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
+                                        <literal>$rpcbind</literal>
+                                        facility.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>rtc-set.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
+                                        <literal>$time</literal>
+                                        facility.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>shutdown.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        that terminates the services
+                                        on system shutdown.</para>
+
+                                        <para>Services that shall be
+                                        terminated on system shutdown
+                                        shall add Wants dependencies
+                                        from this unit to 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>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>sigpwr.target</filename></term>
+                                <listitem>
+                                        <para>A special target that is
+                                        started when systemd receives
+                                        the SIGPWR process signal,
+                                        which is normally sent by the
+                                        kernel or UPS daemons when the
+                                        power fails.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>sockets.target</filename></term>
+                                <listitem>
+                                        <para>A special target unit
+                                        that sets up all service
+                                        sockets.</para>
+
+                                        <para>Services that can be
+                                        socket-activated shall add
+                                        Wants dependencies from this
+                                        unit to their socket unit
+                                        during installation.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>swap.target</filename></term>
+                                <listitem>
+                                        <para>Similar to
+                                        <filename>local-fs.target</filename>, but for swap
+                                        partitions and swap
+                                        files.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>syslog.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
+                                        <literal>$syslog</literal>
+                                        facility.</para>
+
+                                        <para>Administrators should
+                                        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>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>systemd-initctl.service</filename></term>
+                                <listitem>
+                                        <para>This provides
+                                        compatibility with the SysV
+                                        /dev/initctl file system FIFO
+                                        for communication with the
+                                        init system.</para>
+                                        <para>This is a
+                                        socket-activated service, see
+                                        <filename>system-initctl.socket</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>systemd-initctl.socket</filename></term>
+                                <listitem>
+                                        <para>Socket activation unit
+                                        for
+                                        <filename>system-initctl.service</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>systemd-logger.service</filename></term>
+                                <listitem>
+                                        <para>This is used internally
+                                        by systemd to provide syslog
+                                        logging to started
+                                        processes.</para>
+                                        <para>This is a
+                                        socket-activated service, see
+                                        <filename>system-logger.socket</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>systemd-logger.socket</filename></term>
+                                <listitem>
+                                        <para>Socket activation unit
+                                        for
+                                        <filename>system-logger.service</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+        </refsect1>
+
+        <refsect1>
+                <title>Special Session Units</title>
+
+                <para>When systemd runs as a service instance, the
+                following special units are available, which have
+                similar definitions as their system counterparts:
+                <filename>local-fs.target</filename>,
+                <filename>remote-fs.target</filename>,
+                <filename>shutdown.target</filename>,
+                <filename>sockets.target</filename>,
+                <filename>swap.target</filename>.</para>
+        </refsect1>
+
+        <refsect1>
+                  <title>See Also</title>
+                  <para>
+                          <citerefentry><refentrytitle>systemd.unit</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>
+                  </para>
+        </refsect1>
+
+</refentry>
index cfa1b09..4f71ffd 100644 (file)
@@ -77,7 +77,7 @@
 
                 <variablelist>
                         <varlistentry>
 
                 <variablelist>
                         <varlistentry>
-                                <term>Names=</term>
+                                <term><varname>Names=</varname></term>
                                 <listitem>
                                         <para>Additional names for this unit. The names
                                         listed here mus have the same suffix (i.e. type)
                                 <listitem>
                                         <para>Additional names for this unit. The names
                                         listed here mus have the same suffix (i.e. type)
@@ -86,7 +86,7 @@
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term>Requires=</term>
+                                <term><varname>Requires=</varname></term>
                                 <listitem>
                                         <para>Dependencies on other
                                         units. If this units get
                                 <listitem>
                                         <para>Dependencies on other
                                         units. If this units get
index 424ce87..7892300 100644 (file)
@@ -97,10 +97,10 @@ struct Watch {
 #define SPECIAL_SIGPWR_TARGET "sigpwr.target"
 #define SPECIAL_CTRL_ALT_DEL_TARGET "ctrl-alt-del.target"
 
 #define SPECIAL_SIGPWR_TARGET "sigpwr.target"
 #define SPECIAL_CTRL_ALT_DEL_TARGET "ctrl-alt-del.target"
 
-#define SPECIAL_LOCAL_FS_TARGET "local-fs.target"
-#define SPECIAL_REMOTE_FS_TARGET "remote-fs.target"
+#define SPECIAL_LOCAL_FS_TARGET "local-fs.target"         /* LSB's $local_fs */
+#define SPECIAL_REMOTE_FS_TARGET "remote-fs.target"       /* LSB's $remote_fs */
 #define SPECIAL_SWAP_TARGET "swap.target"
 #define SPECIAL_SWAP_TARGET "swap.target"
-#define SPECIAL_NETWORK_TARGET "network.target"
+#define SPECIAL_NETWORK_TARGET "network.target"           /* LSB's $network */
 #define SPECIAL_NSS_LOOKUP_TARGET "nss-lookup.target"     /* LSB's $named */
 #define SPECIAL_RPCBIND_TARGET "rpcbind.target"           /* LSB's $portmap */
 #define SPECIAL_SYSLOG_TARGET "syslog.target"             /* LSB's $syslog; Should pull in syslog.socket or syslog.service */
 #define SPECIAL_NSS_LOOKUP_TARGET "nss-lookup.target"     /* LSB's $named */
 #define SPECIAL_RPCBIND_TARGET "rpcbind.target"           /* LSB's $portmap */
 #define SPECIAL_SYSLOG_TARGET "syslog.target"             /* LSB's $syslog; Should pull in syslog.socket or syslog.service */
index 13fca6f..6c4b870 100644 (file)
@@ -15,6 +15,8 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Emergency Shell
 
 [Unit]
 Description=Emergency Shell
 
index 3e7124a..81bff5a 100644 (file)
@@ -15,5 +15,7 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Local File Systems
 [Unit]
 Description=Local File Systems
index cdb1b5e..a218c64 100644 (file)
@@ -15,5 +15,7 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Network
 [Unit]
 Description=Network
index d1ce0a7..e8e6593 100644 (file)
@@ -15,6 +15,8 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Name Lookups
 Wants=network.target
 [Unit]
 Description=Name Lookups
 Wants=network.target
index 0ed324e..177a773 100644 (file)
@@ -15,6 +15,8 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Remote File Systems
 Requires=network.target
 [Unit]
 Description=Remote File Systems
 Requires=network.target
index 626fa5a..18c1ed3 100644 (file)
@@ -15,5 +15,7 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=RTC Set
 [Unit]
 Description=RTC Set
index 87b1be8..37dca44 100644 (file)
@@ -15,5 +15,7 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Shutdown
 [Unit]
 Description=Shutdown
index 36d4d24..24f7d38 100644 (file)
@@ -15,5 +15,7 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Power Failure
 [Unit]
 Description=Power Failure
index 1061030..00e698f 100644 (file)
@@ -15,5 +15,7 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Sockets
 [Unit]
 Description=Sockets
index aac5456..4f6e193 100644 (file)
@@ -15,5 +15,7 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Swap
 [Unit]
 Description=Swap
index bcd6453..d21e7a7 100644 (file)
@@ -15,6 +15,8 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=Syslog
 Requires=@SPECIAL_SYSLOG_SERVICE@
 [Unit]
 Description=Syslog
 Requires=@SPECIAL_SYSLOG_SERVICE@
index b6d5158..252a014 100644 (file)
@@ -15,6 +15,8 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=systemd /dev/initctl Compatibility Daemon
 
 [Unit]
 Description=systemd /dev/initctl Compatibility Daemon
 
index ff3dbac..acff322 100644 (file)
@@ -15,6 +15,8 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=systemd /dev/initctl Compatibility Socket
 
 [Unit]
 Description=systemd /dev/initctl Compatibility Socket
 
index ba6fa47..e4606ea 100644 (file)
@@ -15,6 +15,8 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=systemd Logging Daemon
 
 [Unit]
 Description=systemd Logging Daemon
 
index a1d11e8..8d02ab4 100644 (file)
@@ -15,6 +15,8 @@
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
 #  You should have received a copy of the GNU General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+# See systemd.special(7) for details
+
 [Unit]
 Description=systemd Logging Socket
 
 [Unit]
 Description=systemd Logging Socket