X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fdaemon.xml;h=a8bbfc055b62f7f1cff4d0b1f9b37f212bb9244e;hb=1cfa9a4cbb41ef770614fa97961cc056a63c1b7c;hp=66e198abbc404214577a8b582f652ad5cee03685;hpb=8a422bb295516bb85fe1e8dbd7ff03a9e9e1a520;p=elogind.git

diff --git a/man/daemon.xml b/man/daemon.xml
index 66e198abb..a8bbfc055 100644
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -1,6 +1,6 @@
 <?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">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
@@ -23,801 +23,630 @@
 
 <refentry id="daemon">
 
-        <refentryinfo>
-                <title>daemon</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>daemon</refentrytitle>
-                <manvolnum>7</manvolnum>
-        </refmeta>
-
-        <refnamediv>
-                <refname>daemon</refname>
-                <refpurpose>Writing and Packaging System Daemons</refpurpose>
-        </refnamediv>
-
-        <refsect1>
-                <title>Description</title>
-
-                <para>A daemon is a service process that runs in the
-                background and supervises the system or provides
-                functionality to other processes. Traditionally,
-                daemons are implemented following a scheme originating
-                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>. 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>
-
-                        <para>When a traditional SysV daemon
-                        starts, it should execute the following steps
-                        as part of the initialization. Note that these
-                        steps are unnecessary for new-style daemons (see below),
-                        and should only be implemented if compatibility
-                        with SysV is essential.</para>
-
-                        <orderedlist>
-                                <listitem><para>Close all open file
-                                descriptors except STDIN, STDOUT,
-                                STDERR (i.e. the first three file
-                                descriptors 0, 1, 2). This ensures
-                                that no accidentally passed file
-                                descriptor stays around in the daemon
-                                process. On Linux this is best
-                                implemented by iterating through
-                                <filename>/proc/self/fd</filename>,
-                                with a fallback of iterating from file
-                                descriptor 3 to the value returned by
-                                <function>getrlimit()</function> for
-                                RLIMIT_NOFILE.</para></listitem>
-
-                                <listitem><para>Reset all signal
-                                handlers to their default. This is
-                                best done by iterating through the
-                                available signals up to the limit of
-                                _NSIG and resetting them to
-                                SIG_DFL.</para></listitem>
-
-                                <listitem><para>Reset the signal mask
-                                using
-                                <function>sigprocmask()</function>.</para></listitem>
-
-                                <listitem><para>Sanitize the
-                                environment block, removing or
-                                resetting environment variables that
-                                might negatively impact daemon
-                                runtime.</para></listitem>
-
-                                <listitem><para>Call <function>fork()</function>,
-                                to create a background
-                                process.</para></listitem>
-
-                                <listitem><para>In the child, call
-                                <function>setsid()</function> to
-                                detach from any terminal and create an
-                                independent session.</para></listitem>
-
-                                <listitem><para>In the child, call
-                                <function>fork()</function> again, to
-                                ensure the daemon can never re-acquire
-                                a terminal again.</para></listitem>
-
-                                <listitem><para>Call <function>exit()</function> in the
-                                first child, so that only the second
-                                child (the actual daemon process)
-                                stays around. This ensures that the
-                                daemon process is reparented to
-                                init/PID 1, as all daemons should
-                                be.</para></listitem>
-
-                                <listitem><para>In the daemon process,
-                                connect <filename>/dev/null</filename>
-                                to STDIN, STDOUT,
-                                STDERR.</para></listitem>
-
-                                <listitem><para>In the daemon process,
-                                reset the umask to 0, so that the file
-                                modes passed to <function>open()</function>, <function>mkdir()</function> and
-                                suchlike directly control the access
-                                mode of the created files and
-                                directories.</para></listitem>
-
-                                <listitem><para>In the daemon process,
-                                change the current directory to the
-                                root directory (/), in order to avoid
-                                that the daemon involuntarily
-                                blocks mount points from being
-                                unmounted.</para></listitem>
-
-                                <listitem><para>In the daemon process,
-                                write the daemon PID (as returned by
-                                <function>getpid()</function>) to a
-                                PID file, for example
-                                <filename>/var/run/foobar.pid</filename>
-                                (for a hypothetical daemon "foobar"),
-                                to ensure that the daemon cannot be
-                                started more than once. This must be
-                                implemented in race-free fashion so
-                                that the PID file is only updated when
-                                at the same time it is verified that
-                                the PID previously stored in the PID
-                                file no longer exists or belongs to a
-                                foreign process. Commonly some kind of
-                                file locking is employed to implement
-                                this logic.</para></listitem>
-
-                                <listitem><para>In the daemon process,
-                                drop privileges, if possible and
-                                applicable.</para></listitem>
-
-                                <listitem><para>From the daemon
-                                process notify the original process
-                                started that initialization is
-                                complete. This can be implemented via
-                                an unnamed pipe or similar
-                                communication channel that is created
-                                before the first
-                                <function>fork()</function> and hence
-                                available in both the original and the
-                                daemon process.</para></listitem>
-
-                                <listitem><para>Call
-                                <function>exit()</function> in the
-                                original process. The process that
-                                invoked the daemon must be able to
-                                rely that this
-                                <function>exit()</function> happens
-                                after initialization is complete and
-                                all external communication channels
-                                established and
-                                accessible.</para></listitem>
-                        </orderedlist>
-
-                        <para>The BSD <function>daemon()</function> function should not be
-                        used, as it implements only a subset of these steps.</para>
-
-                        <para>A daemon that needs to provide
-                        compatibility with SysV systems should
-                        implement the scheme pointed out
-                        above. However, it is recommended to make this
-                        behaviour optional and configurable via a
-                        command line argument, to ease debugging as
-                        well as to simplify integration into systems
-                        using systemd.</para>
-                </refsect2>
-
-                <refsect2>
-                        <title>New-Style Daemons</title>
-
-                        <para>Modern services for Linux should be
-                        implemented as new-style daemons. This makes it
-                        easier to supervise and control them at
-                        runtime and simplifies their
-                        implementation.</para>
-
-                        <para>For developing a new-style daemon none
-                        of the initialization steps recommended for
-                        SysV daemons need to be implemented. New-style
-                        init systems such as systemd make all of them
-                        redundant. Moreover, since some of these steps
-                        interfere with process monitoring, file
-                        descriptor passing and other functionality of
-                        the init system it is recommended not to
-                        execute them when run as new-style
-                        service.</para>
-
-                        <para>Note that new-style init systems
-                        guarantee execution of daemon processes in
-                        clean process contexts: it is guaranteed that
-                        the environment block is sanitized, that the
-                        signal handlers and mask is reset and that no
-                        left-over file descriptors are passed. Daemons
-                        will be executed in their own session, and
-                        STDIN/STDOUT/STDERR connected to
-                        <filename>/dev/null</filename> unless
-                        otherwise configured. The umask is reset.</para>
-
-                        <para>It is recommended for new-style daemons
-                        to implement the following:</para>
-
-                        <orderedlist>
-                                <listitem><para>If SIGTERM is
-                                received, shut down the daemon and
-                                exit cleanly.</para></listitem>
-
-                                <listitem><para>If SIGHUP is received,
-                                reload the configuration files, if
-                                this applies.</para></listitem>
-
-                                <listitem><para>Provide a correct exit
-                                code from the main daemon process, as
-                                this is used by the init system to
-                                detect service errors and problems. It
-                                is recommended to follow the exit code
-                                scheme as defined in the <ulink
-                                url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
-                                recommendations for SysV init
-                                scripts</ulink>.</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
-                                configuration file. This has multiple
-                                advantages: your daemon may be started
-                                lazily on-demand; it may be started in
-                                parallel to other daemons requiring it
-                                -- which maximizes parallelization and
-                                boot-up speed; your daemon can be
-                                restarted on failure, without losing
-                                any bus requests, as the bus queues
-                                requests for activatable services. See
-                                below for details.</para></listitem>
-
-                                <listitem><para>If your daemon
-                                provides services to other local
-                                processes or remote clients via a
-                                socket, it should be made
-                                socket-activatable following the
-                                scheme pointed out below. Like D-Bus
-                                activation this enables on-demand
-                                starting of services as well as it
-                                allows improved parallelization of
-                                service start-up. Also, for state-less
-                                protocols (such as syslog, DNS) a
-                                daemon implementing socket-based
-                                activation can be restarted without
-                                losing a single request. See below for
-                                details.</para></listitem>
-
-                                <listitem><para>If applicable a daemon
-                                should notify the init system about
-                                startup completion or status updates
-                                via the
-                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                                interface.</para></listitem>
-
-                                <listitem><para>Instead of using the
-                                <function>syslog()</function> call to log directly to the
-                                system syslog service, a new-style daemon may
-                                choose to simply log to STDERR via
-                                <function>fprintf()</function>, which is then forwarded to
-                                syslog by the init system. If log
-                                priorities are necessary these can be
-                                encoded by prefixing individual log
-                                lines with strings like "&lt;4&gt;"
-                                (for log priority 4 "WARNING" in the
-                                syslog priority scheme), following a
-                                similar style as the Linux kernel's
-                                <function>printk()</function> priority system. In fact,
-                                using this style of logging also
-                                enables the init system to optionally
-                                direct all application logging to the
-                                kernel log buffer (kmsg), as
-                                accessible via
-                                <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
-                                kind of logging may be enabled by
-                                setting
-                                <varname>StandardError=syslog</varname>
-                                in the service unit file. For details
-                                see
-                                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-                                and
-                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
-
-                        </orderedlist>
-
-                        <para>These recommendations are similar but
-                        not identical to the <ulink
-                        url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">Apple
-                        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 is
-                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 ubiquitously 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 as 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 command like
-                        <command>enable</command> of
-                        <citerefentry><refentrytitle>systemctl</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
-                        bandwidth 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
-                        recommended to consider the following
-                        suggestions:</para>
-
-                        <orderedlist>
-                                <listitem><para>If possible do not use
-                                the <varname>Type=forking</varname>
-                                setting in service files. But if you
-                                do, make sure to set the PID file path
-                                using <varname>PIDFile=</varname>. See
-                                <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                                for details.</para></listitem>
-
-                                <listitem><para>If your daemon
-                                registers a D-Bus name on the bus,
-                                make sure to use
-                                <varname>Type=dbus</varname> in the
-                                service file if
-                                possible.</para></listitem>
-
-                                <listitem><para>Make sure to set a
-                                good human-readable description string
-                                with
-                                <varname>Description=</varname>.</para></listitem>
-
-                                <listitem><para>Do not disable
-                                <varname>DefaultDependencies=</varname>,
-                                unless you really know what you do and
-                                your unit is involved in early boot or
-                                late system shutdown.</para></listitem>
-
-                                <listitem><para>Normally, little if
-                                any dependencies should need to
-                                be defined explicitly. However, if you
-                                do configure explicit dependencies, only refer to
-                                unit names listed on
-                                <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-                                or names introduced by your own
-                                package to keep the unit file
-                                operating
-                                system-independent.</para></listitem>
-
-                                <listitem><para>Make sure to include
-                                an <literal>[Install]</literal>
-                                section including installation
-                                information for the unit file. See
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                                for details. To activate your service
-                                on boot make sure to add a
-                                <varname>WantedBy=multi-user.target</varname>
-                                or
-                                <varname>WantedBy=graphical.target</varname>
-                                directive. To activate your socket on
-                                boot, make sure to add
-                                <varname>WantedBy=sockets.target</varname>. Usually
-                                you also want to make sure that when
-                                your service is installed your socket
-                                is installed too, hence add
-                                <varname>Also=foo.socket</varname> in
-                                your service file
-                                <filename>foo.service</filename>, for
-                                a hypothetical program
-                                <filename>foo</filename>.</para></listitem>
-
-                        </orderedlist>
-                </refsect2>
-
-                <refsect2>
-                        <title>Installing Systemd Service Files</title>
-
-                        <para>At the build installation time
-                        (e.g. <command>make install</command> during
-                        package build) packages are recommended to
-                        install their systemd unit files in the
-                        directory returned by <command>pkg-config
-                        systemd
-                        --variable=systemdsystemunitdir</command> (for
-                        system services), resp. <command>pkg-config
-                        systemd
-                        --variable=systemduserunitdir</command>
-                        (for user services). This will make the
-                        services available in the system on explicit
-                        request but not activate them automatically
-                        during boot. Optionally, during package
-                        installation (e.g. <command>rpm -i</command>
-                        by the administrator) symlinks should be
-                        created in the systemd configuration
-                        directories via the <command>enable</command>
-                        command of the
-                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                        tool, to activate them automatically on
-                        boot.</para>
-
-                        <para>Packages using
-                        <citerefentry><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                        are recommended to use a configure script
-                        excerpt like the following to determine the
-                        unit installation path during source
-                        configuration:</para>
-
-                        <programlisting>PKG_PROG_PKG_CONFIG
+  <refentryinfo>
+    <title>daemon</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>daemon</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>daemon</refname>
+    <refpurpose>Writing and packaging system daemons</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>A daemon is a service process that runs in the background
+    and supervises the system or provides functionality to other
+    processes. Traditionally, daemons are implemented following a
+    scheme originating 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>.
+    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>
+
+      <para>When a traditional SysV daemon starts, it should execute
+      the following steps as part of the initialization. Note that
+      these steps are unnecessary for new-style daemons (see below),
+      and should only be implemented if compatibility with SysV is
+      essential.</para>
+
+      <orderedlist>
+        <listitem><para>Close all open file descriptors except
+        standard input, output, and error (i.e. the first three file
+        descriptors 0, 1, 2). This ensures that no accidentally passed
+        file descriptor stays around in the daemon process. On Linux,
+        this is best implemented by iterating through
+        <filename>/proc/self/fd</filename>, with a fallback of
+        iterating from file descriptor 3 to the value returned by
+        <function>getrlimit()</function> for
+        <constant>RLIMIT_NOFILE</constant>. </para></listitem>
+
+        <listitem><para>Reset all signal handlers to their default.
+        This is best done by iterating through the available signals
+        up to the limit of <constant>_NSIG</constant> and resetting
+        them to <constant>SIG_DFL</constant>.</para></listitem>
+
+        <listitem><para>Reset the signal mask
+        using
+        <function>sigprocmask()</function>.</para></listitem>
+
+        <listitem><para>Sanitize the environment block, removing or
+        resetting environment variables that might negatively impact
+        daemon runtime.</para></listitem>
+
+        <listitem><para>Call <function>fork()</function>, to create a
+        background process.</para></listitem>
+
+        <listitem><para>In the child, call
+        <function>setsid()</function> to detach from any terminal and
+        create an independent session.</para></listitem>
+
+        <listitem><para>In the child, call <function>fork()</function>
+        again, to ensure that the daemon can never re-acquire a
+        terminal again.</para></listitem>
+
+        <listitem><para>Call <function>exit()</function> in the first
+        child, so that only the second child (the actual daemon
+        process) stays around. This ensures that the daemon process is
+        re-parented to init/PID 1, as all daemons should
+        be.</para></listitem>
+
+        <listitem><para>In the daemon process, connect
+        <filename>/dev/null</filename> to standard input, output, and
+        error.</para></listitem>
+
+        <listitem><para>In the daemon process, reset the umask to 0,
+        so that the file modes passed to <function>open()</function>,
+        <function>mkdir()</function> and suchlike directly control the
+        access mode of the created files and
+        directories.</para></listitem>
+
+        <listitem><para>In the daemon process, change the current
+        directory to the root directory (/), in order to avoid that
+        the daemon involuntarily blocks mount points from being
+        unmounted.</para></listitem>
+
+        <listitem><para>In the daemon process, write the daemon PID
+        (as returned by <function>getpid()</function>) to a PID file,
+        for example <filename>/run/foobar.pid</filename> (for a
+        hypothetical daemon "foobar") to ensure that the daemon cannot
+        be started more than once. This must be implemented in
+        race-free fashion so that the PID file is only updated when it
+        is verified at the same time that the PID previously stored in
+        the PID file no longer exists or belongs to a foreign
+        process.</para></listitem>
+
+        <listitem><para>In the daemon process, drop privileges, if
+        possible and applicable.</para></listitem>
+
+        <listitem><para>From the daemon process, notify the original
+        process started that initialization is complete. This can be
+        implemented via an unnamed pipe or similar communication
+        channel that is created before the first
+        <function>fork()</function> and hence available in both the
+        original and the daemon process.</para></listitem>
+
+        <listitem><para>Call <function>exit()</function> in the
+        original process. The process that invoked the daemon must be
+        able to rely on that this <function>exit()</function> happens
+        after initialization is complete and all external
+        communication channels are established and
+        accessible.</para></listitem>
+      </orderedlist>
+
+      <para>The BSD <function>daemon()</function> function should not
+      be used, as it implements only a subset of these steps.</para>
+
+      <para>A daemon that needs to provide compatibility with SysV
+      systems should implement the scheme pointed out above. However,
+      it is recommended to make this behavior optional and
+      configurable via a command line argument to ease debugging as
+      well as to simplify integration into systems using
+      systemd.</para>
+    </refsect2>
+
+    <refsect2>
+      <title>New-Style Daemons</title>
+
+      <para>Modern services for Linux should be implemented as
+      new-style daemons. This makes it easier to supervise and control
+      them at runtime and simplifies their implementation.</para>
+
+      <para>For developing a new-style daemon, none of the
+      initialization steps recommended for SysV daemons need to be
+      implemented. New-style init systems such as systemd make all of
+      them redundant. Moreover, since some of these steps interfere
+      with process monitoring, file descriptor passing and other
+      functionality of the init system, it is recommended not to
+      execute them when run as new-style service.</para>
+
+      <para>Note that new-style init systems guarantee execution of
+      daemon processes in a clean process context: it is guaranteed
+      that the environment block is sanitized, that the signal
+      handlers and mask is reset and that no left-over file
+      descriptors are passed. Daemons will be executed in their own
+      session, with standard input/output/error connected to
+      <filename>/dev/null</filename> unless otherwise configured. The
+      umask is reset.
+      </para>
+
+      <para>It is recommended for new-style daemons to implement the
+      following:</para>
+
+      <orderedlist>
+        <listitem><para>If <constant>SIGTERM</constant> is received,
+        shut down the daemon and exit cleanly.</para></listitem>
+
+        <listitem><para>If <constant>SIGHUP</constant> is received,
+        reload the configuration files, if this
+        applies.</para></listitem>
+
+        <listitem><para>Provide a correct exit code from the main
+        daemon process, as this is used by the init system to detect
+        service errors and problems. It is recommended to follow the
+        exit code scheme as defined in the <ulink
+        url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
+        recommendations for SysV init
+        scripts</ulink>.</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 system'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 by supplying a D-Bus service activation
+        configuration file. This has multiple advantages: your daemon
+        may be started lazily on-demand; it may be started in parallel
+        to other daemons requiring it -- which maximizes
+        parallelization and boot-up speed; your daemon can be
+        restarted on failure without losing any bus requests, as the
+        bus queues requests for activatable services. See below for
+        details.</para></listitem>
+
+        <listitem><para>If your daemon provides services to other
+        local processes or remote clients via a socket, it should be
+        made socket-activatable following the scheme pointed out
+        below. Like D-Bus activation, this enables on-demand starting
+        of services as well as it allows improved parallelization of
+        service start-up. Also, for state-less protocols (such as
+        syslog, DNS), a daemon implementing socket-based activation
+        can be restarted without losing a single request. See below
+        for details.</para></listitem>
+
+        <listitem><para>If applicable, a daemon should notify the init
+        system about startup completion or status updates via the
+        <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+        interface.</para></listitem>
+
+        <listitem><para>Instead of using the
+        <function>syslog()</function> call to log directly to the
+        system syslog service, a new-style daemon may choose to simply
+        log to standard error via <function>fprintf()</function>,
+        which is then forwarded to syslog by the init system. If log
+        levels are necessary, these can be encoded by prefixing
+        individual log lines with strings like
+        <literal>&lt;4&gt;</literal> (for log level 4 "WARNING" in the
+        syslog priority scheme), following a similar style as the
+        Linux kernel's <function>printk()</function> level system. For
+        details, see
+        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+        and
+        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+
+      </orderedlist>
+
+      <para>These recommendations are similar but not identical to the
+      <ulink
+      url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple
+      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 is 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.linuxbase.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 ubiquitously 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 that 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
+      as 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
+      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>3</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 command like <command>enable</command>
+      of
+      <citerefentry><refentrytitle>systemctl</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, there are often 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
+      <constant>IP_FREEBIND</constant> 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 bandwidth 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 recommended to
+      consider the following suggestions:</para>
+
+      <orderedlist>
+        <listitem><para>If possible, do not use the
+        <varname>Type=forking</varname> setting in service files. But
+        if you do, make sure to set the PID file path using
+        <varname>PIDFile=</varname>. See
+        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        for details.</para></listitem>
+
+        <listitem><para>If your daemon registers a D-Bus name on the
+        bus, make sure to use <varname>Type=dbus</varname> in the
+        service file if possible.</para></listitem>
+
+        <listitem><para>Make sure to set a good human-readable
+        description string with
+        <varname>Description=</varname>.</para></listitem>
+
+        <listitem><para>Do not disable
+        <varname>DefaultDependencies=</varname>, unless you really
+        know what you do and your unit is involved in early boot or
+        late system shutdown.</para></listitem>
+
+        <listitem><para>Normally, little if any dependencies should
+        need to be defined explicitly. However, if you do configure
+        explicit dependencies, only refer to unit names listed on
+        <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+        or names introduced by your own package to keep the unit file
+        operating system-independent.</para></listitem>
+
+        <listitem><para>Make sure to include an
+        <literal>[Install]</literal> section including installation
+        information for the unit file. See
+        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        for details. To activate your service on boot, make sure to
+        add a <varname>WantedBy=multi-user.target</varname> or
+        <varname>WantedBy=graphical.target</varname> directive. To
+        activate your socket on boot, make sure to add
+        <varname>WantedBy=sockets.target</varname>. Usually, you also
+        want to make sure that when your service is installed, your
+        socket is installed too, hence add
+        <varname>Also=foo.socket</varname> in your service file
+        <filename>foo.service</filename>, for a hypothetical program
+        <filename>foo</filename>.</para></listitem>
+
+      </orderedlist>
+    </refsect2>
+
+    <refsect2>
+      <title>Installing Systemd Service Files</title>
+
+      <para>At the build installation time (e.g. <command>make
+      install</command> during package build), packages are
+      recommended to install their systemd unit files in the directory
+      returned by <command>pkg-config systemd
+      --variable=systemdsystemunitdir</command> (for system services)
+      or <command>pkg-config systemd
+      --variable=systemduserunitdir</command> (for user services).
+      This will make the services available in the system on explicit
+      request but not activate them automatically during boot.
+      Optionally, during package installation (e.g. <command>rpm
+      -i</command> by the administrator), symlinks should be created
+      in the systemd configuration directories via the
+      <command>enable</command> command of the
+      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      tool to activate them automatically on boot.</para>
+
+      <para>Packages using
+      <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      are recommended to use a configure script
+      excerpt like the following to determine the
+      unit installation path during source
+      configuration:</para>
+
+      <programlisting>PKG_PROG_PKG_CONFIG
 AC_ARG_WITH([systemdsystemunitdir],
-        AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
-        [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
-if test "x$with_systemdsystemunitdir" != xno; then
-        AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
-fi
-AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ])</programlisting>
-
-                        <para>This snippet allows automatic
-                        installation of the unit files on systemd
-                        machines, and optionally allows their
-                        installation even on machines lacking
-                        systemd. (Modification of this snippet for the
-                        user unit directory is left as an exercise for the
-                        reader.)</para>
-
-                        <para>Additionally, to ensure that
-                        <command>make distcheck</command> continues to
-                        work, it is recommended to add the following
-                        to the top-level <filename>Makefile.am</filename>
-                        file in
-                        <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
-                        projects:</para>
-
-                        <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
-        --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>
-
-                        <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
-
-                        <programlisting>if HAVE_SYSTEMD
+     [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],,
+     [with_systemdsystemunitdir=auto])
+AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [
+     def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)
+
+     AS_IF([test "x$def_systemdsystemunitdir" = "x"],
+   [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"],
+    [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])])
+    with_systemdsystemunitdir=no],
+   [with_systemdsystemunitdir="$def_systemdsystemunitdir"])])
+AS_IF([test "x$with_systemdsystemunitdir" != "xno"],
+      [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])])
+AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</programlisting>
+
+      <para>This snippet allows automatic
+      installation of the unit files on systemd
+      machines, and optionally allows their
+      installation even on machines lacking
+      systemd. (Modification of this snippet for the
+      user unit directory is left as an exercise for the
+      reader.)</para>
+
+      <para>Additionally, to ensure that
+      <command>make distcheck</command> continues to
+      work, it is recommended to add the following
+      to the top-level <filename>Makefile.am</filename>
+      file in
+      <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
+      projects:</para>
+
+      <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
+  --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>
+
+      <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
+
+      <programlisting>if HAVE_SYSTEMD
 systemdsystemunit_DATA = \
-        foobar.socket \
-        foobar.service
+  foobar.socket \
+  foobar.service
 endif</programlisting>
 
-                        <para>In the
-                        <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-                        <filename>.spec</filename> file use snippets
-                        like the following to enable/disable the
-                        service during
-                        installation/deinstallation. This makes use of
-                        the RPM macros shipped along systemd. Consult
-                        the packaging guidelines of your distribution
-                        for details and the equivalent for other
-                        package managers.</para>
+      <para>In the
+      <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      <filename>.spec</filename> file, use snippets like the following
+      to enable/disable the service during
+      installation/deinstallation. This makes use of the RPM macros
+      shipped along systemd. Consult the packaging guidelines of your
+      distribution for details and the equivalent for other package
+      managers.</para>
 
-                        <para>At the top of the file:</para>
+      <para>At the top of the file:</para>
 
-                        <programlisting>BuildRequires: systemd
+      <programlisting>BuildRequires: systemd
 %{?systemd_requires}</programlisting>
 
-                        <para>And as scriptlets, further down:</para>
+      <para>And as scriptlets, further down:</para>
 
-                        <programlisting>%post
+      <programlisting>%post
 %systemd_post foobar.service foobar.socket
 
 %preun
@@ -826,124 +655,111 @@ endif</programlisting>
 %postun
 %systemd_postun</programlisting>
 
-                        <para>If the service shall be restarted during
-                        upgrades replace the
-                        <literal>%postun</literal> scriptlet above
-                        with the following:</para>
+      <para>If the service shall be restarted during upgrades, replace
+      the <literal>%postun</literal> scriptlet above with the
+      following:</para>
 
-                        <programlisting>%postun
+      <programlisting>%postun
 %systemd_postun_with_restart foobar.service</programlisting>
 
-                        <para>Note that
-                        <literal>%systemd_post</literal> and
-                        <literal>%systemd_preun</literal> expect the
-                        names of all units that are installed/removed
-                        as arguments, separated by
-                        spaces. <literal>%systemd_postun</literal>
-                        expects no
-                        arguments. <literal>%systemd_postun_with_restart</literal>
-                        expects the units to restart as
-                        arguments.</para>
-
-                        <para>To facilitate upgrades from a package
-                        version that shipped only SysV init scripts to
-                        a package version that ships both a SysV init
-                        script and a native systemd service file, use
-                        a fragment like the following:</para>
-
-                        <programlisting>%triggerun -- foobar &lt; 0.47.11-1
+      <para>Note that <literal>%systemd_post</literal> and
+      <literal>%systemd_preun</literal> expect the names of all units
+      that are installed/removed as arguments, separated by spaces.
+      <literal>%systemd_postun</literal> expects no arguments.
+      <literal>%systemd_postun_with_restart</literal> expects the
+      units to restart as arguments.</para>
+
+      <para>To facilitate upgrades from a package version that shipped
+      only SysV init scripts to a package version that ships both a
+      SysV init script and a native systemd service file, use a
+      fragment like the following:</para>
+
+      <programlisting>%triggerun -- foobar &lt; 0.47.11-1
 if /sbin/chkconfig --level 5 foobar ; then
-        /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+  /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
 fi</programlisting>
 
-                        <para>Where 0.47.11-1 is the first package
-                        version that includes the native unit
-                        file. This fragment will ensure that the first
-                        time the unit file is installed it will be
-                        enabled if and only if the SysV init script is
-                        enabled, thus making sure that the enable
-                        status is not changed. Note that
-                        <command>chkconfig</command> is a command
-                        specific to Fedora which can be used to check
-                        whether a SysV init script is enabled. Other
-                        operating systems will have to use different
-                        commands here.</para>
-                </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 so offers additional
-                functionality to the daemons as well as simplifying
-                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 sockets 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>
-                <para>
-                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                        <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>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                </para>
-        </refsect1>
+      <para>Where 0.47.11-1 is the first package version that includes
+      the native unit file. This fragment will ensure that the first
+      time the unit file is installed, it will be enabled if and only
+      if the SysV init script is enabled, thus making sure that the
+      enable status is not changed. Note that
+      <command>chkconfig</command> is a command specific to Fedora
+      which can be used to check whether a SysV init script is
+      enabled. Other operating systems will have to use different
+      commands here.</para>
+    </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 so
+    offers additional functionality to the daemons as well as
+    simplifying 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
+      <constant>AF_UNIX</constant> 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 <constant>AF_UNIX</constant> 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 sockets 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>Placing Daemon Data</title>
+
+    <para>It is recommended to follow the general guidelines for
+    placing package files, as discussed in
+    <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</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>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    </para>
+  </refsect1>
 
 </refentry>