0066eddda7203f6345b56f77d146a759298dc635gryzor<?xml version='1.0'?> <!--*-nxml-*-->

0066eddda7203f6345b56f77d146a759298dc635gryzor<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

fd9abdda70912b99b24e3bf1a38f26fde908a74cnd "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

fd9abdda70912b99b24e3bf1a38f26fde908a74cnd

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor<refentry id="daemon">

3f08db06526d6901aa08c110b5bc7dde6bc39905nd

0066eddda7203f6345b56f77d146a759298dc635gryzor <refentryinfo>

0066eddda7203f6345b56f77d146a759298dc635gryzor <title>daemon</title>

0066eddda7203f6345b56f77d146a759298dc635gryzor <productname>systemd</productname>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <authorgroup>

0066eddda7203f6345b56f77d146a759298dc635gryzor <author>

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <contrib>Developer</contrib>

0066eddda7203f6345b56f77d146a759298dc635gryzor <firstname>Lennart</firstname>

0066eddda7203f6345b56f77d146a759298dc635gryzor <surname>Poettering</surname>

0066eddda7203f6345b56f77d146a759298dc635gryzor <email>lennart@poettering.net</email>

0066eddda7203f6345b56f77d146a759298dc635gryzor </author>

0066eddda7203f6345b56f77d146a759298dc635gryzor </authorgroup>

0066eddda7203f6345b56f77d146a759298dc635gryzor </refentryinfo>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <refmeta>

0066eddda7203f6345b56f77d146a759298dc635gryzor <refentrytitle>daemon</refentrytitle>

0066eddda7203f6345b56f77d146a759298dc635gryzor <manvolnum>7</manvolnum>

0066eddda7203f6345b56f77d146a759298dc635gryzor </refmeta>

853ab6827637acc5cdd976cd2ea20a18f82ae184lgentis

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh <refnamediv>

4aa603e6448b99f9371397d439795c91a93637eand <refname>daemon</refname>

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh <refpurpose>Writing and packaging system daemons</refpurpose>

0066eddda7203f6345b56f77d146a759298dc635gryzor </refnamediv>

173e5f4d5ec46b5febb74ce860d753bb1faaba0fsf

0066eddda7203f6345b56f77d146a759298dc635gryzor <refsect1>

0066eddda7203f6345b56f77d146a759298dc635gryzor <title>Description</title>

0066eddda7203f6345b56f77d146a759298dc635gryzor

853ab6827637acc5cdd976cd2ea20a18f82ae184lgentis <para>A daemon is a service process that runs in the

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh background and supervises the system or provides

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh functionality to other processes. Traditionally,

4aa603e6448b99f9371397d439795c91a93637eand daemons are implemented following a scheme originating

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh in SysV Unix. Modern daemons should follow a simpler

0066eddda7203f6345b56f77d146a759298dc635gryzor yet more powerful scheme (here called "new-style"

0066eddda7203f6345b56f77d146a759298dc635gryzor daemons), as implemented by

0066eddda7203f6345b56f77d146a759298dc635gryzor <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This

0066eddda7203f6345b56f77d146a759298dc635gryzor manual page covers both schemes, and in

0066eddda7203f6345b56f77d146a759298dc635gryzor particular includes recommendations for daemons that

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar shall be included in the systemd init system.</para>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <refsect2>

0066eddda7203f6345b56f77d146a759298dc635gryzor <title>SysV Daemons</title>

764f77465841302c4fb205a035754fc8398dcf1frbowen

0066eddda7203f6345b56f77d146a759298dc635gryzor <para>When a traditional SysV daemon

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar starts, it should execute the following steps

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar as part of the initialization. Note that these

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar steps are unnecessary for new-style daemons (see below),

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar and should only be implemented if compatibility

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar with SysV is essential.</para>

564ee5b847469eb8a61120179ce70a0213965785rbowen

0066eddda7203f6345b56f77d146a759298dc635gryzor <orderedlist>

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>Close all open file

0066eddda7203f6345b56f77d146a759298dc635gryzor descriptors except STDIN, STDOUT,

0066eddda7203f6345b56f77d146a759298dc635gryzor STDERR (i.e. the first three file

0066eddda7203f6345b56f77d146a759298dc635gryzor descriptors 0, 1, 2). This ensures

0066eddda7203f6345b56f77d146a759298dc635gryzor that no accidentally passed file

0066eddda7203f6345b56f77d146a759298dc635gryzor descriptor stays around in the daemon

0066eddda7203f6345b56f77d146a759298dc635gryzor process. On Linux this is best

0066eddda7203f6345b56f77d146a759298dc635gryzor implemented by iterating through

0066eddda7203f6345b56f77d146a759298dc635gryzor <filename>/proc/self/fd</filename>,

0066eddda7203f6345b56f77d146a759298dc635gryzor with a fallback of iterating from file

0066eddda7203f6345b56f77d146a759298dc635gryzor descriptor 3 to the value returned by

0066eddda7203f6345b56f77d146a759298dc635gryzor <function>getrlimit()</function> for

0066eddda7203f6345b56f77d146a759298dc635gryzor RLIMIT_NOFILE.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>Reset all signal

0066eddda7203f6345b56f77d146a759298dc635gryzor handlers to their default. This is

0066eddda7203f6345b56f77d146a759298dc635gryzor best done by iterating through the

0066eddda7203f6345b56f77d146a759298dc635gryzor available signals up to the limit of

0066eddda7203f6345b56f77d146a759298dc635gryzor _NSIG and resetting them to

853ab6827637acc5cdd976cd2ea20a18f82ae184lgentis SIG_DFL.</para></listitem>

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh <listitem><para>Reset the signal mask

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh using

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh <function>sigprocmask()</function>.</para></listitem>

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh <listitem><para>Sanitize the

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh environment block, removing or

4aa603e6448b99f9371397d439795c91a93637eand resetting environment variables that

fe2be2903c65e2f99f04199655ea5f97a75825d0humbedooh might negatively impact daemon

0066eddda7203f6345b56f77d146a759298dc635gryzor runtime.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>Call <function>fork()</function>,

0066eddda7203f6345b56f77d146a759298dc635gryzor to create a background

0066eddda7203f6345b56f77d146a759298dc635gryzor process.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>In the child, call

0066eddda7203f6345b56f77d146a759298dc635gryzor <function>setsid()</function> to

0066eddda7203f6345b56f77d146a759298dc635gryzor detach from any terminal and create an

0066eddda7203f6345b56f77d146a759298dc635gryzor independent session.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>In the child, call

0066eddda7203f6345b56f77d146a759298dc635gryzor <function>fork()</function> again, to

0066eddda7203f6345b56f77d146a759298dc635gryzor ensure the daemon can never re-acquire

0066eddda7203f6345b56f77d146a759298dc635gryzor a terminal again.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>Call <function>exit()</function> in the

0066eddda7203f6345b56f77d146a759298dc635gryzor first child, so that only the second

0066eddda7203f6345b56f77d146a759298dc635gryzor child (the actual daemon process)

0066eddda7203f6345b56f77d146a759298dc635gryzor stays around. This ensures that the

0066eddda7203f6345b56f77d146a759298dc635gryzor daemon process is re-parented to

0066eddda7203f6345b56f77d146a759298dc635gryzor init/PID 1, as all daemons should

0066eddda7203f6345b56f77d146a759298dc635gryzor be.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>In the daemon process,

0066eddda7203f6345b56f77d146a759298dc635gryzor connect <filename>/dev/null</filename>

0066eddda7203f6345b56f77d146a759298dc635gryzor to STDIN, STDOUT,

0066eddda7203f6345b56f77d146a759298dc635gryzor STDERR.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>In the daemon process,

0066eddda7203f6345b56f77d146a759298dc635gryzor reset the umask to 0, so that the file

764f77465841302c4fb205a035754fc8398dcf1frbowen modes passed to <function>open()</function>, <function>mkdir()</function> and

764f77465841302c4fb205a035754fc8398dcf1frbowen suchlike directly control the access

e609ac39f206eb484d7d609a6a50369b1abbe112sf mode of the created files and

764f77465841302c4fb205a035754fc8398dcf1frbowen directories.</para></listitem>

e609ac39f206eb484d7d609a6a50369b1abbe112sf

e609ac39f206eb484d7d609a6a50369b1abbe112sf <listitem><para>In the daemon process,

e609ac39f206eb484d7d609a6a50369b1abbe112sf change the current directory to the

e609ac39f206eb484d7d609a6a50369b1abbe112sf root directory (/), in order to avoid

e609ac39f206eb484d7d609a6a50369b1abbe112sf that the daemon involuntarily

e609ac39f206eb484d7d609a6a50369b1abbe112sf blocks mount points from being

e609ac39f206eb484d7d609a6a50369b1abbe112sf unmounted.</para></listitem>

e609ac39f206eb484d7d609a6a50369b1abbe112sf

e609ac39f206eb484d7d609a6a50369b1abbe112sf <listitem><para>In the daemon process,

e609ac39f206eb484d7d609a6a50369b1abbe112sf write the daemon PID (as returned by

764f77465841302c4fb205a035754fc8398dcf1frbowen <function>getpid()</function>) to a

764f77465841302c4fb205a035754fc8398dcf1frbowen PID file, for example

0066eddda7203f6345b56f77d146a759298dc635gryzor <filename>/var/run/foobar.pid</filename>

0066eddda7203f6345b56f77d146a759298dc635gryzor (for a hypothetical daemon "foobar"),

0066eddda7203f6345b56f77d146a759298dc635gryzor to ensure that the daemon cannot be

0066eddda7203f6345b56f77d146a759298dc635gryzor started more than once. This must be

0066eddda7203f6345b56f77d146a759298dc635gryzor implemented in race-free fashion so

0066eddda7203f6345b56f77d146a759298dc635gryzor that the PID file is only updated when

0066eddda7203f6345b56f77d146a759298dc635gryzor at the same time it is verified that

0066eddda7203f6345b56f77d146a759298dc635gryzor the PID previously stored in the PID

0066eddda7203f6345b56f77d146a759298dc635gryzor file no longer exists or belongs to a

0066eddda7203f6345b56f77d146a759298dc635gryzor foreign process. Commonly some kind of

0066eddda7203f6345b56f77d146a759298dc635gryzor file locking is employed to implement

d5f93073383d85ebb0e4b77ae5bff13551a45dd9nd this logic.</para></listitem>

d5f93073383d85ebb0e4b77ae5bff13551a45dd9nd

d5f93073383d85ebb0e4b77ae5bff13551a45dd9nd <listitem><para>In the daemon process,

d5f93073383d85ebb0e4b77ae5bff13551a45dd9nd drop privileges, if possible and

0066eddda7203f6345b56f77d146a759298dc635gryzor applicable.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <listitem><para>From the daemon

0066eddda7203f6345b56f77d146a759298dc635gryzor process notify the original process

0066eddda7203f6345b56f77d146a759298dc635gryzor started that initialization is

d5f93073383d85ebb0e4b77ae5bff13551a45dd9nd complete. This can be implemented via

0066eddda7203f6345b56f77d146a759298dc635gryzor an unnamed pipe or similar

d5f93073383d85ebb0e4b77ae5bff13551a45dd9nd communication channel that is created

d5f93073383d85ebb0e4b77ae5bff13551a45dd9nd before the first

0066eddda7203f6345b56f77d146a759298dc635gryzor <function>fork()</function> and hence

0066eddda7203f6345b56f77d146a759298dc635gryzor available in both the original and the

0066eddda7203f6345b56f77d146a759298dc635gryzor daemon process.</para></listitem>

0066eddda7203f6345b56f77d146a759298dc635gryzor

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <listitem><para>Call

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <function>exit()</function> in the

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar original process. The process that

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar invoked the daemon must be able to

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar rely on that this

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <function>exit()</function> happens

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar after initialization is complete and

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar all external communication channels

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar are established and

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar accessible.</para></listitem>

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar </orderedlist>

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <para>The BSD <function>daemon()</function> function should not be

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar used, as it implements only a subset of these steps.</para>

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <para>A daemon that needs to provide

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar compatibility with SysV systems should

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar implement the scheme pointed out

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar above. However, it is recommended to make this

1f1b6bf13313fdd14a45e52e553d3ff28689b717coar behavior optional and configurable via a

0066eddda7203f6345b56f77d146a759298dc635gryzor command line argument, to ease debugging as

0066eddda7203f6345b56f77d146a759298dc635gryzor well as to simplify integration into systems

0066eddda7203f6345b56f77d146a759298dc635gryzor using systemd.</para>

0066eddda7203f6345b56f77d146a759298dc635gryzor </refsect2>

0066eddda7203f6345b56f77d146a759298dc635gryzor

0066eddda7203f6345b56f77d146a759298dc635gryzor <refsect2>

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <title>New-Style Daemons</title>

727872d18412fc021f03969b8641810d8896820bhumbedooh

0d0ba3a410038e179b695446bb149cce6264e0abnd <para>Modern services for Linux should be

727872d18412fc021f03969b8641810d8896820bhumbedooh implemented as new-style daemons. This makes it

cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh easier to supervise and control them at

0d0ba3a410038e179b695446bb149cce6264e0abnd runtime and simplifies their

cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh implementation.</para>

727872d18412fc021f03969b8641810d8896820bhumbedooh

0d0ba3a410038e179b695446bb149cce6264e0abnd <para>For developing a new-style daemon none

0d0ba3a410038e179b695446bb149cce6264e0abnd of the initialization steps recommended for

0d0ba3a410038e179b695446bb149cce6264e0abnd SysV daemons need to be implemented. New-style

ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh init systems such as systemd make all of them

0d0ba3a410038e179b695446bb149cce6264e0abnd redundant. Moreover, since some of these steps

0d0ba3a410038e179b695446bb149cce6264e0abnd interfere with process monitoring, file

0d0ba3a410038e179b695446bb149cce6264e0abnd descriptor passing and other functionality of

727872d18412fc021f03969b8641810d8896820bhumbedooh the init system it is recommended not to

0d0ba3a410038e179b695446bb149cce6264e0abnd execute them when run as new-style

0d0ba3a410038e179b695446bb149cce6264e0abnd service.</para>

30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh

205f749042ed530040a4f0080dbcb47ceae8a374rjung <para>Note that new-style init systems

af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen guarantee execution of daemon processes in

0d0ba3a410038e179b695446bb149cce6264e0abnd clean process contexts: it is guaranteed that

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd the environment block is sanitized, that the

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd signal handlers and mask is reset and that no

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd left-over file descriptors are passed. Daemons

0066eddda7203f6345b56f77d146a759298dc635gryzor 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 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, 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>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="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

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, 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) 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><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

systemdsystemunit_DATA = \

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>At the top of the file:</para>

<programlisting>BuildRequires: systemd

%{?systemd_requires}</programlisting>

<para>And as scriptlets, further down:</para>

<programlisting>%post

%systemd_post foobar.service foobar.socket

%preun

%systemd_preun foobar.service foobar.socket

%postun

%systemd_postun</programlisting>

<para>If the service shall be restarted during

upgrades replace the

<literal>%postun</literal> scriptlet above

with the following:</para>

<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

if /sbin/chkconfig --level 5 foobar ; then

/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>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>

</para>

</refsect1>

</refentry>