man: add missing parts to man pages

3 files changed, 503 insertions, 101 deletions

diff --git a/man/daemon.xml b/man/daemon.xml
index 853b3bb814..01ab0f3b51 100644
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -57,7 +57,10 @@
                 in SysV Unix. Modern daemons should follow a simpler
                 yet more powerful scheme (here called "new-style"
                 daemons), as implemented by
-                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para>
+                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
+                manual page covers both schemes, and in
+                particular includes recommendations for daemons that
+                shall be included in the systemd init system.</para>
 
                 <refsect2>
                         <title>SysV Daemons</title>
@@ -252,26 +255,35 @@
                                 recommendations for SysV init
                                 scripts</ulink>.</para></listitem>
 
-                                <listitem><para>As much as possible,
-                                rely on systemd's functionality to
-                                limit the access of the daemon to
-                                files, services and other
-                                resources. i.e. rely on systemd's
-                                resource limit control instead of
-                                implementing your own, rely on
-                                systemd's privilege dropping code
-                                instead of implementing it in the
-                                daemon, and similar. See
-                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                                for the available
-                                controls.</para></listitem>
-
                                 <listitem><para>If possible and
                                 applicable expose the daemon's control
                                 interface via the D-Bus IPC system and
                                 grab a bus name as last step of
                                 initialization.</para></listitem>
 
+                                <listitem><para>For integration in
+                                systemd, provide a
+                                <filename>.service</filename> unit
+                                file that carries information about
+                                starting, stopping and otherwise
+                                maintaining the daemon. See
+                                <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                for details.</para></listitem>
+
+                                <listitem><para>As much as possible,
+                                rely on the init systemd's
+                                functionality to limit the access of
+                                the daemon to files, services and
+                                other resources. i.e. in the case of
+                                systemd, rely on systemd's resource
+                                limit control instead of implementing
+                                your own, rely on systemd's privilege
+                                dropping code instead of implementing
+                                it in the daemon, and similar. See
+                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                for the available
+                                controls.</para></listitem>
+
                                 <listitem><para>If D-Bus is used, make
                                 your daemon bus-activatable, via
                                 supplying a D-Bus service activation
@@ -345,19 +357,309 @@
                         MacOS X Daemon Requirements</ulink>.</para>
                 </refsect2>
 
+        </refsect1>
+        <refsect1>
+                <title>Activation</title>
+
+                <para>New-style init systems provide multiple
+                additional mechanisms to activate services, as
+                detailed below. It is common that services are
+                configured to be activated via more than one mechanism
+                at the same time. An example for systemd:
+                <filename>bluetoothd.service</filename> might get
+                activated either when Bluetooth hardware is plugged
+                in, or when an application accesses its programming
+                interfaces via D-Bus. Or, a print server daemon might
+                get activated when traffic arrives at an IPP port, or
+                when a printer is plugged in, or when a file is queued
+                in the printer spool directory. Even for services that
+                are intended to be started on system bootup
+                unconditionally it is a good idea to implement some of
+                the various activation schemes outlined below, in
+                order to maximize parallelization: if a daemon
+                implements a D-Bus service or listening socket,
+                implementing the full bus and socket activation scheme
+                allows starting of the daemon with its clients in
+                parallel (which speeds up boot-up), since all its
+                communication channels are established already, and no
+                request is lost because client requests will be queued
+                by the bus system (in case of D-Bus) or the kernel (in
+                case of sockets), until the activation
+                completed.</para>
+
+                <refsect2>
+                        <title>Activation on Boot</title>
+
+                        <para>Old-style daemons are usually activated
+                        exclusively on boot (and manually by the
+                        administrator) via SysV init scripts, as
+                        detailed in the <ulink
+                        url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
+                        Linux Standard Base Core
+                        Specification</ulink>. This method of
+                        activation is supported ubiquitiously on Linux
+                        init systems, both old-style and new-style
+                        systems. Among other issues SysV init scripts
+                        have the disadvantage of involving shell
+                        scripts in the boot process. New-style init
+                        systems generally employ updated versions of
+                        activation, both during boot-up and during
+                        runtime and using more minimal service
+                        description files.</para>
+
+                        <para>In systemd, if the developer or
+                        administrator wants to make sure a service or
+                        other unit is activated automatically on boot
+                        it is recommended to place a symlink to the
+                        unit file in the <filename>.wants/</filename>
+                        directory of either
+                        <filename>multi-user.target</filename> or
+                        <filename>graphical.target</filename>, which
+                        are normally used as boot targets at system
+                        startup. See
+                        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        for details about the
+                        <filename>.wants/</filename> directories, and
+                        <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                        for details about the two boot targets.</para>
+
+                </refsect2>
+
                 <refsect2>
                         <title>Socket-Based Activation</title>
+
+                        <para>In order to maximize the possible
+                        parallelization and robustness and simplify
+                        configuration and development, it is
+                        recommended for all new-style daemons that
+                        communicate via listening sockets to employ
+                        socket-based activation. In a socket-based
+                        activation scheme the creation and binding of
+                        the listening socket as primary communication
+                        channel of daemons to local (and sometimes
+                        remote) clients is moved out of the daemon
+                        code and into the init system. Based on
+                        per-daemon configuration the init system
+                        installs the sockets and then hands them off
+                        to the spawned process as soon as the
+                        respective daemon is to be started.
+                        Optionally activation of the service can be
+                        delayed until the first inbound traffic
+                        arrives at the socket, to implement on-demand
+                        activation of daemons. However, the primary
+                        advantage of this scheme is that all providers
+                        and all consumers of the sockets can be
+                        started in parallel as soon als all sockets
+                        are established. In addition to that daemons
+                        can be restarted with losing only a minimal
+                        number of client transactions or even any
+                        client request at all (the latter is
+                        particularly true for state-less protocols,
+                        such as DNS or syslog), because the socket
+                        stays bound and accessible during the restart,
+                        and all requests are queued while the daemon
+                        cannot process them.</para>
+
+                        <para>New-style daemons which support socket
+                        activation must be able to receive their
+                        sockets from the init system, instead of of
+                        creating and binding them themselves. For
+                        details about the programming interfaces for
+                        this scheme provided by systemd see
+                        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                        and
+                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For
+                        details about porting existing daemons to
+                        socket-based activation see below. With
+                        minimal effort it is possible to implement
+                        socket-based activation in addition to
+                        traditional internal socket creation in the
+                        same codebase in order to support both
+                        new-style and old-style init systems from the
+                        same daemon binary.</para>
+
+                        <para>systemd implements socket-based
+                        activation via <filename>.socket</filename>
+                        units, which are described in
+                        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. When
+                        configuring socket units for socket-based
+                        activation it is essential that all listening
+                        sockets are pulled in by the special target
+                        unit <filename>sockets.target</filename>. It
+                        is recommended to place a
+                        <varname>WantedBy=sockets.target</varname>
+                        directive in the <literal>[Install]</literal>
+                        section, to automatically add such a
+                        dependency on installation of a socket
+                        unit. Unless
+                        <varname>DefaultDependencies=no</varname> is
+                        set the necessary ordering dependencies are
+                        implicitly created for all socket units. For
+                        more information about
+                        <filename>sockets.target</filename> see
+                        <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. It
+                        is not necessary or recommended to place any
+                        additional dependencies on socket units (for
+                        example from
+                        <filename>multi-user.target</filename> or
+                        suchlike) when one is installed in
+                        <filename>sockets.target</filename>.</para>
                 </refsect2>
 
                 <refsect2>
                         <title>Bus-Based Activation</title>
+
+                        <para>When the D-Bus IPC system is used for
+                        communication with clients, new-style daemons
+                        should employ bus activation so that they are
+                        automatically activated when a client
+                        application accesses their IPC
+                        interfaces. This is configured in D-Bus
+                        service files (not to be confused with systemd
+                        service unit files!). To ensure that D-Bus
+                        uses systemd to start-up and maintain the
+                        daemon use the
+                        <varname>SystemdService=</varname> directive
+                        in these service files, to configure the
+                        matching systemd service for a D-Bus
+                        service. e.g.: for a D-Bus service whose D-Bus
+                        activation file is named
+                        <filename>org.freedesktop.RealtimeKit.service</filename>,
+                        make sure to set
+                        <varname>SystemdService=rtkit-daemon.service</varname>
+                        in that file, to bind it to the systemd
+                        service
+                        <filename>rtkit-daemon.service</filename>. This
+                        is needed to make sure that the daemon is
+                        started in a race-free fashion when activated
+                        via multiple mechanisms simultaneously.</para>
+                </refsect2>
+
+                <refsect2>
+                        <title>Device-Based Activation</title>
+
+                        <para>Often, daemons that manage a particular
+                        type of hardware should be activated only when
+                        the hardware of the respective kind is plugged
+                        in or otherwise becomes available. In a
+                        new-style init system it is possible to bind
+                        activation to hardware plug/unplug events. In systemd,
+                        kernel devices appearing in the sysfs/udev
+                        device tree can be exposed as units if they
+                        are tagged with the string
+                        "<literal>systemd</literal>". Like any other
+                        kind of unit they may then pull in other units
+                        when activated (i.e. Plugged in) and thus
+                        implement device-based activation. Systemd
+                        dependencies may be encoded in the udev
+                        database via the
+                        <varname>SYSTEMD_WANTS=</varname>
+                        property. See
+                        <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        for details. Often it is nicer to pull in
+                        services from devices only indirectly via
+                        dedicated targets. Example: instead of pulling
+                        in <filename>bluetoothd.service</filename>
+                        from all the various bluetooth dongles and
+                        other hardware available, pull in
+                        bluetooth.target from them and
+                        <filename>bluetoothd.service</filename> from
+                        that target. This provides for nicer
+                        abstraction and gives administrators the
+                        option to enable
+                        <filename>bluetoothd.service</filename> via
+                        controlling a
+                        <filename>bluetooth.target.wants/</filename>
+                        symlink uniformly with a tool like
+                        <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        instead of manipulating the udev
+                        ruleset.</para>
                 </refsect2>
 
                 <refsect2>
                         <title>Path-Based Activation</title>
+
+                        <para>Often, runtime of daemons processing
+                        spool files or directories (such as a printing
+                        system) can be delayed until these file system
+                        objects change state, or become
+                        non-empty. New-style init systems provide a
+                        way to bind service activation to file system
+                        changes. systemd implements this scheme via
+                        path-based activation configured in
+                        <filename>.path</filename> units, as outlined
+                        in
+                        <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+                </refsect2>
+
+                <refsect2>
+                        <title>Timer-Based Activation</title>
+
+                        <para>Some daemons that implement clean-up
+                        jobs that are intended to be executed in
+                        regular intervals benefit from timer-based
+                        activation. In systemd, this is implemented
+                        via <filename>.timer</filename> units, as
+                        described in
+                        <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
                 </refsect2>
 
                 <refsect2>
+                        <title>Other Forms of Activation</title>
+
+                        <para>Other forms of activation have been
+                        suggested and implemented in some
+                        systems. However, often there are simpler or
+                        better alternatives, or they can be put
+                        together of combinations of the schemes
+                        above. Example: sometimes it appears useful to
+                        start daemons or <filename>.socket</filename>
+                        units when a specific IP address is configured
+                        on a network interface, because network
+                        sockets shall be bound to the
+                        address. However, an alternative to implement
+                        this is by utilizing the Linux IP_FREEBIND
+                        socket option, as accessible via
+                        <varname>FreeBind=yes</varname> in systemd
+                        socket files (see
+                        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        for details). This option, when enabled,
+                        allows sockets to be bound to a non-local, not
+                        configured IP address, and hence allows
+                        bindings to a particular IP address before it
+                        actually becomes available, making such an
+                        explicit dependency to the configured address
+                        redundant. Another often suggested trigger for
+                        service activation is low system
+                        load. However, here too, a more convincing
+                        approach might be to make proper use of
+                        features of the operating system: in
+                        particular, the CPU or IO scheduler of
+                        Linux. Instead of scheduling jobs from
+                        userspace based on monitoring the OS
+                        scheduler, it is advisable to leave the
+                        scheduling of processes to the OS scheduler
+                        itself. systemd provides fine-grained access
+                        to the CPU and IO schedulers. If a process
+                        executed by the init system shall not
+                        negatively impact the amount of CPU or IO
+                        bandwith available to other processes, it
+                        should be configured with
+                        <varname>CPUSchedulingPolicy=idle</varname>
+                        and/or
+                        <varname>IOSchedulingClass=idle</varname>. Optionally,
+                        this may be combined with timer-based
+                        activation to schedule background jobs during
+                        runtime and with minimal impact on the system,
+                        and remove it from the boot phase
+                        itself.</para>
+                </refsect2>
+
+        </refsect1>
+        <refsect1>
+                <title>Integration with Systemd</title>
+
+                <refsect2>
                         <title>Writing Systemd Unit Files</title>
 
                         <para>When writing systemd unit files, it is
@@ -416,7 +718,7 @@
                 </refsect2>
 
                 <refsect2>
-                        <title>Installing Service Files</title>
+                        <title>Installing Systemd Service Files</title>
 
                         <para>At the build installation time
                         (e.g. <command>make install</command> during
@@ -488,7 +790,7 @@ endif</programlisting>
                         during installation/deinstallation. Consult
                         the packaging guidelines of your distribution
                         for details and the equivalent for other
-                        packaging managers:</para>
+                        package managers:</para>
 
                         <programlisting>%post
 /usr/bin/systemd-install enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
@@ -499,85 +801,70 @@ if [ "$1" -eq 0 ]; then
 fi</programlisting>
 
                 </refsect2>
-
-                <refsect2>
-                        <title>Porting Existing Daemons</title>
-
-                        <para>Since new-style init systems such as
-                        systemd are compatible with traditional SysV
-                        init systems it is not strictly necessary to
-                        port existing daemons to the new
-                        style. However doing this offers additional
-                        functionality to the daemons as well as it
-                        simplifies integration into new-style init
-                        systems.</para>
-
-                        <para>To port an existing SysV compatible
-                        daemon the following steps are
-                        recommended:</para>
-
-                        <orderedlist>
-                                <listitem><para>If not already
-                                implemented, add an optional command
-                                line switch to the daemon to disable
-                                daemonization. This is useful not only
-                                for using the daemon in new-style init
-                                systems, but also to ease debugging.</para></listitem>
-
-                                <listitem><para>If the daemon offers
-                                interfaces to other software running
-                                on the local system via local AF_UNIX
-                                sockets, consider implementing
-                                socket-based activation (see
-                                above). Usually a minimal patch is
-                                sufficient to implement this: Extend
-                                the socket creation in the daemon code
-                                so that
-                                <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                                is checked for already passed sockets
-                                first. If sockets are passed
-                                (i.e. when
-                                <function>sd_listen_fds()</function>
-                                returns a positive value), skip the
-                                socket createn step and use the passed
-                                sockets. Secondly, ensure that the
-                                file-system socket nodes for local
-                                AF_UNIX sockets used in the
-                                socket-based activation are not
-                                removed when the daemon shuts down, if
-                                sockets have been passed. Third, if
-                                the daemon normally closes all
-                                remaining open file descriptors as
-                                part of its initialization, the
-                                sockets passed from the init system
-                                must be spared. Since new-style init
-                                systems guarantee that no left-over
-                                file descriptors are passed to
-                                executed processes, it might be a good
-                                choice to simply skip the closing of
-                                all remaining open file descriptors if
-                                file descriptors are
-                                passed.</para></listitem>
-
-                                <listitem><para>Write and install a
-                                systemd unit file for the service (and
-                                the sockets if socket-based activation
-                                is used, as well as a path unit file,
-                                if the daemon processes a spool
-                                directory), see above for
-                                details.</para></listitem>
-
-                                <listitem><para>If the daemon exposes
-                                interfaces via D-Bus, write and
-                                install a D-Bus activation file for
-                                the service, see above for
-                                details.</para></listitem>
-                        </orderedlist>
-
-                </refsect2>
-
         </refsect1>
 
+        <refsect1>
+                <title>Porting Existing Daemons</title>
+
+                <para>Since new-style init systems such as systemd are
+                compatible with traditional SysV init systems it is
+                not strictly necessary to port existing daemons to the
+                new style. However doing this offers additional
+                functionality to the daemons as well as it simplifies
+                integration into new-style init systems.</para>
+
+                <para>To port an existing SysV compatible daemon the
+                following steps are recommended:</para>
+
+                <orderedlist>
+                        <listitem><para>If not already implemented,
+                        add an optional command line switch to the
+                        daemon to disable daemonization. This is
+                        useful not only for using the daemon in
+                        new-style init systems, but also to ease
+                        debugging.</para></listitem>
+
+                        <listitem><para>If the daemon offers
+                        interfaces to other software running on the
+                        local system via local AF_UNIX sockets,
+                        consider implementing socket-based activation
+                        (see above). Usually a minimal patch is
+                        sufficient to implement this: Extend the
+                        socket creation in the daemon code so that
+                        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                        is checked for already passed sockets
+                        first. If sockets are passed (i.e. when
+                        <function>sd_listen_fds()</function> returns a
+                        positive value), skip the socket creation step
+                        and use the passed sockets. Secondly, ensure
+                        that the file-system socket nodes for local
+                        AF_UNIX sockets used in the socket-based
+                        activation are not removed when the daemon
+                        shuts down, if sockets have been
+                        passed. Third, if the daemon normally closes
+                        all remaining open file descriptors as part of
+                        its initialization, the sockets passed from
+                        the init system must be spared. Since
+                        new-style init systems guarantee that no
+                        left-over file descriptors are passed to
+                        executed processes, it might be a good choice
+                        to simply skip the closing of all remaining
+                        open file descriptors if file descriptors are
+                        passed.</para></listitem>
+
+                        <listitem><para>Write and install a systemd
+                        unit file for the service (and the sockets if
+                        socket-based activation is used, as well as a
+                        path unit file, if the daemon processes a
+                        spool directory), see above for
+                        details.</para></listitem>
+
+                        <listitem><para>If the daemon exposes
+                        interfaces via D-Bus, write and install a
+                        D-Bus activation file for the service, see
+                        above for details.</para></listitem>
+                </orderedlist>
+        </refsect1>
 
         <refsect1>
                 <title>See Also</title>
@@ -587,7 +874,8 @@ fi</programlisting>
                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>
         </refsect1>
 
diff --git a/man/systemd.device.xml b/man/systemd.device.xml
index a5395a1d48..c5306430fb 100644
--- a/man/systemd.device.xml
+++ b/man/systemd.device.xml
@@ -64,9 +64,11 @@
                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 for the common options of all unit configuration
                 files. The common configuration items are configured
-                in the generic [Unit] and [Install] sections. A
-                separate [Device] section does not exist, since no
-                device-specific options may be configured.</para>
+                in the generic <literal>[Unit]</literal> and
+                <literal>[Install]</literal> sections. A separate
+                <literal>[Device]</literal> section does not exist,
+                since no device-specific options may be
+                configured.</para>
 
                 <para>systemd will automatically create dynamic device
                 units for all kernel devices that are marked with the
@@ -100,9 +102,15 @@
                                 <listitem><para>Adds dependencies of
                                 type <varname>Wants</varname> from
                                 this unit to all listed units. This
-                                may be used to activate arbitrary units,
-                                when a specific device becomes
-                                available.</para></listitem>
+                                may be used to activate arbitrary
+                                units, when a specific device becomes
+                                available. Note that this and the
+                                other tags are not taken into account
+                                unless the device is tagged with the
+                                "<literal>systemd</literal>" string in
+                                the udev database, because otherwise
+                                the device is not exposed as systemd
+                                unit.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
diff --git a/man/systemd.xml b/man/systemd.xml
index 27756723b1..007705e494 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -197,6 +197,112 @@
         </refsect1>
 
         <refsect1>
+                <title>Concepts</title>
+
+                <para>systemd provides a dependency system between
+                various entities called "units". Units encapsulate
+                various objects that are relevant for system boot-up
+                and maintainance. The majority of units are configured
+                in unit configuration files, whose syntax and basic
+                set of options is described in
+                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                however some are created automatically from other
+                configuration or dynamically from system state. Units
+                may be active (meaning started, bound, plugged in, ...
+                depending on the unit type), or inactive (meaning
+                stopped, unbound, unplugged, ...), as well is in the
+                process of being activated or deactivated,
+                i.e. between the two states. The following unit types
+                are available:</para>
+
+                <orderedlist>
+                        <listitem><para>Service units, which control
+                        daemons and the processes they consist of. For
+                        details see
+                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Socket units, which
+                        encapsulate local IPC or network sockets in
+                        the system, useful for socket-based
+                        activation. For details about socket units see
+                        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        for details on socket-based activation and
+                        other forms of activation, see
+                        <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Target units are useful to
+                        group units, or provide well-known
+                        synchronization points during boot-up, see
+                        <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Device units expose kernel
+                        devices in systemd and may be used to
+                        implement device-based activation. For details
+                        see
+                        <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Mount units control mount
+                        points in the file system, for details see
+                        <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Automount units provide
+                        automount capabilities, for on-demand mounting
+                        of file systems as well as parallelized
+                        boot-up. See
+                        <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Snapshot units can be used to
+                        temporarily save the state of the set of
+                        systemd units, which later may be restored by
+                        activating the saved snapshot unit. For more
+                        information see
+                        <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Timer units are useful for
+                        triggering activation of other units based on
+                        timers. You may find details in
+                        <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Swap units are very similar to
+                        mount units and encapsulated memory swap
+                        partitions or files of the operating
+                        systemd. They are described in <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                        <listitem><para>Path units may be used
+                        activate other services when file system
+                        objects change or are modified. See
+                        <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+                </orderedlist>
+
+                <para>Units are named as their configuration
+                files. Some units have special semantics. A detailed
+                list you may find in
+                <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
+
+                <para>On boot systemd activates the target unit
+                <filename>default.target</filename> whose job it is to
+                activate on-boot services and other on-boot units by
+                pulling them in via dependencies. Usually the unit
+                name is just an alias (symlink) for either
+                <filename>graphical.target</filename> (for
+                fully-featured boots into the UI) or
+                <filename>multi-user.target</filename> (for limited
+                console-only boots for use in embedded or server
+                environments, or similar; a subset of
+                graphical.target). However it is at the discretion of
+                the administrator to configure it as an alias to any
+                other target unit. See
+                <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                for details about these target units.</para>
+
+                <para>For more information about the concepts and
+                ideas behind systemd please refer to the <ulink
+                url="http://0pointer.de/blog/projects/systemd.html">Original
+                Announcement Document</ulink>.</para>
+        </refsect1>
+
+        <refsect1>
                 <title>Directories</title>
 
                 <variablelist>