daemon.xml revision e0e009c067aa7237f9683c46e5845bbb11ec67c2
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end This file is part of systemd.
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end Copyright 2010 Lennart Poettering
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc systemd is free software; you can redistribute it and/or modify it
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end under the terms of the GNU Lesser General Public License as published by
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end the Free Software Foundation; either version 2.1 of the License, or
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen (at your option) any later version.
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen systemd is distributed in the hope that it will be useful, but
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen WITHOUT ANY WARRANTY; without even the implied warranty of
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end Lesser General Public License for more details.
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen You should have received a copy of the GNU Lesser General Public License
3f08db06526d6901aa08c110b5bc7dde6bc39905nd along with systemd; If not, see <http://www.gnu.org/licenses/>.
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <refentryinfo>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <authorgroup>
e0cfea1f5d38eeaa8fdf7c197c3c1eb31148e191nilgun </authorgroup>
e0cfea1f5d38eeaa8fdf7c197c3c1eb31148e191nilgun </refentryinfo>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <refnamediv>
e0cfea1f5d38eeaa8fdf7c197c3c1eb31148e191nilgun <refpurpose>Writing and packaging system daemons</refpurpose>
e0cfea1f5d38eeaa8fdf7c197c3c1eb31148e191nilgun </refnamediv>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <refsect1>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <para>A daemon is a service process that runs in the
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end background and supervises the system or provides
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end functionality to other processes. Traditionally,
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end daemons are implemented following a scheme originating
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end in SysV Unix. Modern daemons should follow a simpler
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end yet more powerful scheme (here called "new-style"
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end daemons), as implemented by
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end manual page covers both schemes, and in
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end particular includes recommendations for daemons that
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end shall be included in the systemd init system.</para>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <refsect2>
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd <para>When a traditional SysV daemon
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi starts, it should execute the following steps
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd as part of the initialization. Note that these
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd steps are unnecessary for new-style daemons (see below),
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end and should only be implemented if compatibility
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd with SysV is essential.</para>
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd <orderedlist>
f3ec420152ca921e4c1ce77782f51b53f659018dnd descriptors except STDIN, STDOUT,
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd STDERR (i.e. the first three file
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd descriptors 0, 1, 2). This ensures
f3ec420152ca921e4c1ce77782f51b53f659018dnd that no accidentally passed file
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd descriptor stays around in the daemon
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd process. On Linux, this is best
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end implemented by iterating through
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi with a fallback of iterating from file
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi descriptor 3 to the value returned by
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd handlers to their default. This is
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd best done by iterating through the
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end available signals up to the limit of
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd _NSIG and resetting them to
f3ec420152ca921e4c1ce77782f51b53f659018dnd environment block, removing or
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd resetting environment variables that
b9f522ae1c0ed2bf3fc4444245bf28b2e2449a65nd might negatively impact daemon
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end to create a background
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end detach from any terminal and create an
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end ensure that the daemon can never re-acquire
cd34a6fbf0a2619544a72eadb73f309370bf6682wrowe <listitem><para>Call <function>exit()</function> in the
cd34a6fbf0a2619544a72eadb73f309370bf6682wrowe first child, so that only the second
1ac39787115a288f5e848344b1b1e8dccb1c58f1nd child (the actual daemon process)
cd34a6fbf0a2619544a72eadb73f309370bf6682wrowe stays around. This ensures that the
cd34a6fbf0a2619544a72eadb73f309370bf6682wrowe daemon process is re-parented to
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi to STDIN, STDOUT,
4b311579b2c8aebac85fb7cb8ac89e6c37b4bc1asf reset the umask to 0, so that the file
4b311579b2c8aebac85fb7cb8ac89e6c37b4bc1asf modes passed to <function>open()</function>, <function>mkdir()</function> and
4b311579b2c8aebac85fb7cb8ac89e6c37b4bc1asf suchlike directly control the access
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi mode of the created files and
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end change the current directory to the
4b311579b2c8aebac85fb7cb8ac89e6c37b4bc1asf root directory (/), in order to avoid
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end that the daemon involuntarily
4b311579b2c8aebac85fb7cb8ac89e6c37b4bc1asf blocks mount points from being
4b311579b2c8aebac85fb7cb8ac89e6c37b4bc1asf write the daemon PID (as returned by
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end PID file, for example
aa2ff7f8e8477e2b9d20dc2e72737d6bd5145465sf (for a hypothetical daemon "foobar")
aa2ff7f8e8477e2b9d20dc2e72737d6bd5145465sf to ensure that the daemon cannot be
aa2ff7f8e8477e2b9d20dc2e72737d6bd5145465sf started more than once. This must be
acf65805923cf80834c39689cc0e2a8e7201c186sf implemented in race-free fashion so
acf65805923cf80834c39689cc0e2a8e7201c186sf that the PID file is only updated when
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end it is verified at the same time that
acf65805923cf80834c39689cc0e2a8e7201c186sf the PID previously stored in the PID
acf65805923cf80834c39689cc0e2a8e7201c186sf file no longer exists or belongs to a
acf65805923cf80834c39689cc0e2a8e7201c186sf foreign process. Commonly, some kind of
acf65805923cf80834c39689cc0e2a8e7201c186sf file locking is employed to implement
acf65805923cf80834c39689cc0e2a8e7201c186sf drop privileges, if possible and
acf65805923cf80834c39689cc0e2a8e7201c186sf process, notify the original process
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end started that initialization is
acf65805923cf80834c39689cc0e2a8e7201c186sf complete. This can be implemented via
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end an unnamed pipe or similar
acf65805923cf80834c39689cc0e2a8e7201c186sf communication channel that is created
acf65805923cf80834c39689cc0e2a8e7201c186sf before the first
acf65805923cf80834c39689cc0e2a8e7201c186sf available in both the original and the
acf65805923cf80834c39689cc0e2a8e7201c186sf original process. The process that
623eebe956d9c2d6d073ed3eae855b56030b40e9noodl invoked the daemon must be able to
acf65805923cf80834c39689cc0e2a8e7201c186sf rely on that this
acf65805923cf80834c39689cc0e2a8e7201c186sf after initialization is complete and
acf65805923cf80834c39689cc0e2a8e7201c186sf all external communication channels
acf65805923cf80834c39689cc0e2a8e7201c186sf are established and
acf65805923cf80834c39689cc0e2a8e7201c186sf </orderedlist>
acf65805923cf80834c39689cc0e2a8e7201c186sf <para>The BSD <function>daemon()</function> function should not be
acf65805923cf80834c39689cc0e2a8e7201c186sf used, as it implements only a subset of these steps.</para>
acf65805923cf80834c39689cc0e2a8e7201c186sf <para>A daemon that needs to provide
acf65805923cf80834c39689cc0e2a8e7201c186sf compatibility with SysV systems should
acf65805923cf80834c39689cc0e2a8e7201c186sf implement the scheme pointed out
acf65805923cf80834c39689cc0e2a8e7201c186sf above. However, it is recommended to make this
acf65805923cf80834c39689cc0e2a8e7201c186sf behavior optional and configurable via a
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end command line argument to ease debugging as
acf65805923cf80834c39689cc0e2a8e7201c186sf well as to simplify integration into systems
b41a0dbe6310c576e96b7ea6910051fd84fb06f5sf using systemd.</para>
acf65805923cf80834c39689cc0e2a8e7201c186sf </refsect2>
acf65805923cf80834c39689cc0e2a8e7201c186sf <refsect2>
acf65805923cf80834c39689cc0e2a8e7201c186sf <para>Modern services for Linux should be
acf65805923cf80834c39689cc0e2a8e7201c186sf implemented as new-style daemons. This makes it
acf65805923cf80834c39689cc0e2a8e7201c186sf easier to supervise and control them at
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end runtime and simplifies their
acf65805923cf80834c39689cc0e2a8e7201c186sf implementation.</para>
acf65805923cf80834c39689cc0e2a8e7201c186sf <para>For developing a new-style daemon, none
b41a0dbe6310c576e96b7ea6910051fd84fb06f5sf of the initialization steps recommended for
acf65805923cf80834c39689cc0e2a8e7201c186sf SysV daemons need to be implemented. New-style
b41a0dbe6310c576e96b7ea6910051fd84fb06f5sf init systems such as systemd make all of them
4044e4b6cb07cf7fa8e90676fafffe543c1d439bjim redundant. Moreover, since some of these steps
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end interfere with process monitoring, file
acf65805923cf80834c39689cc0e2a8e7201c186sf descriptor passing and other functionality of
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end the init system, it is recommended not to
acf65805923cf80834c39689cc0e2a8e7201c186sf execute them when run as new-style
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end service.</para>
acf65805923cf80834c39689cc0e2a8e7201c186sf <para>Note that new-style init systems
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end guarantee execution of daemon processes in
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end a clean process context: it is guaranteed that
acf65805923cf80834c39689cc0e2a8e7201c186sf the environment block is sanitized, that the
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end signal handlers and mask is reset and that no
acf65805923cf80834c39689cc0e2a8e7201c186sf left-over file descriptors are passed. Daemons
acf65805923cf80834c39689cc0e2a8e7201c186sf will be executed in their own session, and
acf65805923cf80834c39689cc0e2a8e7201c186sf otherwise configured. The umask is reset.</para>
acf65805923cf80834c39689cc0e2a8e7201c186sf <para>It is recommended for new-style daemons
acf65805923cf80834c39689cc0e2a8e7201c186sf to implement the following:</para>
abde5157296f0b860f7551d8a80fa5dffa20e6cajim <orderedlist>
acf65805923cf80834c39689cc0e2a8e7201c186sf received, shut down the daemon and
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <listitem><para>If <constant>SIGHUP</constant> is received,
65a611af7093423efb91e5794b8887a527d4cf63trawick reload the configuration files, if
65a611af7093423efb91e5794b8887a527d4cf63trawick code from the main daemon process, as
65a611af7093423efb91e5794b8887a527d4cf63trawick this is used by the init system to
acf65805923cf80834c39689cc0e2a8e7201c186sf detect service errors and problems. It
acf65805923cf80834c39689cc0e2a8e7201c186sf is recommended to follow the exit code
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end scheme as defined in the <ulink
acf65805923cf80834c39689cc0e2a8e7201c186sf url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end recommendations for SysV init
acf65805923cf80834c39689cc0e2a8e7201c186sf applicable, expose the daemon's control
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end interface via the D-Bus IPC system and
acf65805923cf80834c39689cc0e2a8e7201c186sf grab a bus name as last step of
cd6c8de3bedcc401ee230159b0439fa20f44488etakashi systemd, provide a
bf7a66e941926dc62fd3e0a2b5ba3420ffdc2eb6sf file that carries information about
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end starting, stopping and otherwise
acf65805923cf80834c39689cc0e2a8e7201c186sf maintaining the daemon. See
acf65805923cf80834c39689cc0e2a8e7201c186sf <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
acf65805923cf80834c39689cc0e2a8e7201c186sf rely on the init system's
bf7a66e941926dc62fd3e0a2b5ba3420ffdc2eb6sf functionality to limit the access of
acf65805923cf80834c39689cc0e2a8e7201c186sf the daemon to files, services and
acf65805923cf80834c39689cc0e2a8e7201c186sf other resources, i.e. in the case of
f3ec420152ca921e4c1ce77782f51b53f659018dnd systemd, rely on systemd's resource
acf65805923cf80834c39689cc0e2a8e7201c186sf limit control instead of implementing
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi your own, rely on systemd's privilege
acf65805923cf80834c39689cc0e2a8e7201c186sf dropping code instead of implementing
acf65805923cf80834c39689cc0e2a8e7201c186sf it in the daemon, and similar. See
acf65805923cf80834c39689cc0e2a8e7201c186sf <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
acf65805923cf80834c39689cc0e2a8e7201c186sf for the available
acf65805923cf80834c39689cc0e2a8e7201c186sf your daemon bus-activatable by
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end supplying a D-Bus service activation
acf65805923cf80834c39689cc0e2a8e7201c186sf configuration file. This has multiple
acf65805923cf80834c39689cc0e2a8e7201c186sf advantages: your daemon may be started
acf65805923cf80834c39689cc0e2a8e7201c186sf lazily on-demand; it may be started in
acf65805923cf80834c39689cc0e2a8e7201c186sf parallel to other daemons requiring it
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end -- which maximizes parallelization and
acf65805923cf80834c39689cc0e2a8e7201c186sf boot-up speed; your daemon can be
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end restarted on failure without losing
acf65805923cf80834c39689cc0e2a8e7201c186sf any bus requests, as the bus queues
acf65805923cf80834c39689cc0e2a8e7201c186sf requests for activatable services. See
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end provides services to other local
acf65805923cf80834c39689cc0e2a8e7201c186sf processes or remote clients via a
acf65805923cf80834c39689cc0e2a8e7201c186sf socket, it should be made
acf65805923cf80834c39689cc0e2a8e7201c186sf socket-activatable following the
acf65805923cf80834c39689cc0e2a8e7201c186sf scheme pointed out below. Like D-Bus
acf65805923cf80834c39689cc0e2a8e7201c186sf activation, this enables on-demand
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end starting of services as well as it
acf65805923cf80834c39689cc0e2a8e7201c186sf allows improved parallelization of
acf65805923cf80834c39689cc0e2a8e7201c186sf service start-up. Also, for state-less
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end protocols (such as syslog, DNS), a
acf65805923cf80834c39689cc0e2a8e7201c186sf daemon implementing socket-based
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end activation can be restarted without
acf65805923cf80834c39689cc0e2a8e7201c186sf losing a single request. See below for
dd2f29c187db35e7635ce67a83dddceb75be87a4minfrin should notify the init system about
acf65805923cf80834c39689cc0e2a8e7201c186sf startup completion or status updates
45d66a3a49ac14b7f18cd4d733c1947801b55172sf <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
f5a398cc8880978754903f9ece8e4beb63a81cedrbowen <function>syslog()</function> call to log directly to the
c1621f589e6e26efc55db89e59c9f445580856cctrawick system syslog service, a new-style daemon may
f5a398cc8880978754903f9ece8e4beb63a81cedrbowen choose to simply log to STDERR via
acf65805923cf80834c39689cc0e2a8e7201c186sf <function>fprintf()</function>, which is then forwarded to
f5a398cc8880978754903f9ece8e4beb63a81cedrbowen syslog by the init system. If log
acf65805923cf80834c39689cc0e2a8e7201c186sf priorities are necessary, these can be
f5a398cc8880978754903f9ece8e4beb63a81cedrbowen encoded by prefixing individual log
acf65805923cf80834c39689cc0e2a8e7201c186sf lines with strings like "<4>"
acf65805923cf80834c39689cc0e2a8e7201c186sf (for log priority 4 "WARNING" in the
acf65805923cf80834c39689cc0e2a8e7201c186sf syslog priority scheme), following a
acf65805923cf80834c39689cc0e2a8e7201c186sf similar style as the Linux kernel's
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <function>printk()</function> priority system. In fact,
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton using this style of logging also
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton enables the init system to optionally
db8dceaf53a26fba6048c2ad4d86c5507344187drbowen direct all application logging to the
c1621f589e6e26efc55db89e59c9f445580856cctrawick kernel log buffer (kmsg), as
c1621f589e6e26efc55db89e59c9f445580856cctrawick accessible via
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
c1621f589e6e26efc55db89e59c9f445580856cctrawick kind of logging may be enabled by
f4cbda69df0490c6deaacb8d04f103d200ddd183nd in the service unit file. For details,
f4cbda69df0490c6deaacb8d04f103d200ddd183nd <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
c1621f589e6e26efc55db89e59c9f445580856cctrawick </orderedlist>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <para>These recommendations are similar but
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi not identical to the <ulink
c1621f589e6e26efc55db89e59c9f445580856cctrawick url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">Apple
c1621f589e6e26efc55db89e59c9f445580856cctrawick </refsect2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick </refsect1>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <para>New-style init systems provide multiple
c1621f589e6e26efc55db89e59c9f445580856cctrawick additional mechanisms to activate services, as
c1621f589e6e26efc55db89e59c9f445580856cctrawick detailed below. It is common that services are
c1621f589e6e26efc55db89e59c9f445580856cctrawick configured to be activated via more than one mechanism
0237f43ab925775250e266e479d0a337ff374a4btakashi at the same time. An example for systemd:
0237f43ab925775250e266e479d0a337ff374a4btakashi activated either when Bluetooth hardware is plugged
c1621f589e6e26efc55db89e59c9f445580856cctrawick in, or when an application accesses its programming
c1621f589e6e26efc55db89e59c9f445580856cctrawick interfaces via D-Bus. Or, a print server daemon might
0237f43ab925775250e266e479d0a337ff374a4btakashi get activated when traffic arrives at an IPP port, or
c1621f589e6e26efc55db89e59c9f445580856cctrawick when a printer is plugged in, or when a file is queued
0237f43ab925775250e266e479d0a337ff374a4btakashi in the printer spool directory. Even for services that
c1621f589e6e26efc55db89e59c9f445580856cctrawick are intended to be started on system bootup
c1621f589e6e26efc55db89e59c9f445580856cctrawick unconditionally, it is a good idea to implement some of
0237f43ab925775250e266e479d0a337ff374a4btakashi the various activation schemes outlined below, in
c1621f589e6e26efc55db89e59c9f445580856cctrawick order to maximize parallelization. If a daemon
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi implements a D-Bus service or listening socket,
e05e9b1990428410383f42a260dfaf9b8067f24dnilgun implementing the full bus and socket activation scheme
c1621f589e6e26efc55db89e59c9f445580856cctrawick allows starting of the daemon with its clients in
c1621f589e6e26efc55db89e59c9f445580856cctrawick parallel (which speeds up boot-up), since all its
c1621f589e6e26efc55db89e59c9f445580856cctrawick communication channels are established already, and no
c1621f589e6e26efc55db89e59c9f445580856cctrawick request is lost because client requests will be queued
c1621f589e6e26efc55db89e59c9f445580856cctrawick by the bus system (in case of D-Bus) or the kernel (in
c1621f589e6e26efc55db89e59c9f445580856cctrawick case of sockets) until the activation is
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end completed.</para>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <para>Old-style daemons are usually activated
c1621f589e6e26efc55db89e59c9f445580856cctrawick exclusively on boot (and manually by the
c1621f589e6e26efc55db89e59c9f445580856cctrawick administrator) via SysV init scripts, as
c1621f589e6e26efc55db89e59c9f445580856cctrawick detailed in the <ulink
c1621f589e6e26efc55db89e59c9f445580856cctrawick url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
c1621f589e6e26efc55db89e59c9f445580856cctrawick Linux Standard Base Core
c1621f589e6e26efc55db89e59c9f445580856cctrawick Specification</ulink>. This method of
f3ec420152ca921e4c1ce77782f51b53f659018dnd activation is supported ubiquitously on Linux
c1621f589e6e26efc55db89e59c9f445580856cctrawick init systems, both old-style and new-style
604c89126c27104f659d7a51b0113e3bd435faf8fielding systems. Among other issues, SysV init scripts
604c89126c27104f659d7a51b0113e3bd435faf8fielding have the disadvantage of involving shell
c1621f589e6e26efc55db89e59c9f445580856cctrawick scripts in the boot process. New-style init
c1621f589e6e26efc55db89e59c9f445580856cctrawick systems generally employ updated versions of
9f0c535f81304713568808c9ab2f05b75583fd16nilgun activation, both during boot-up and during
9f0c535f81304713568808c9ab2f05b75583fd16nilgun runtime and using more minimal service
9f0c535f81304713568808c9ab2f05b75583fd16nilgun description files.</para>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <para>In systemd, if the developer or
c1621f589e6e26efc55db89e59c9f445580856cctrawick administrator wants to make sure that a service or
c1621f589e6e26efc55db89e59c9f445580856cctrawick other unit is activated automatically on boot,
c1621f589e6e26efc55db89e59c9f445580856cctrawick it is recommended to place a symlink to the
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar directory of either
c1621f589e6e26efc55db89e59c9f445580856cctrawick are normally used as boot targets at system
c1621f589e6e26efc55db89e59c9f445580856cctrawick startup. See
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
c1621f589e6e26efc55db89e59c9f445580856cctrawick for details about the
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
c1621f589e6e26efc55db89e59c9f445580856cctrawick for details about the two boot targets.</para>
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun </refsect2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <para>In order to maximize the possible
dfc5f686a6ac416a480f0281c9ff0a751013fcf2nilgun parallelization and robustness and simplify
c1621f589e6e26efc55db89e59c9f445580856cctrawick configuration and development, it is
1462ff536f1b939bb337766b2056109c29664c4erbowen recommended for all new-style daemons that
c1621f589e6e26efc55db89e59c9f445580856cctrawick communicate via listening sockets to employ
c1621f589e6e26efc55db89e59c9f445580856cctrawick socket-based activation. In a socket-based
c1621f589e6e26efc55db89e59c9f445580856cctrawick activation scheme, the creation and binding of
c1621f589e6e26efc55db89e59c9f445580856cctrawick the listening socket as primary communication
c1621f589e6e26efc55db89e59c9f445580856cctrawick channel of daemons to local (and sometimes
c1621f589e6e26efc55db89e59c9f445580856cctrawick remote) clients is moved out of the daemon
c1621f589e6e26efc55db89e59c9f445580856cctrawick code and into the init system. Based on
c1621f589e6e26efc55db89e59c9f445580856cctrawick per-daemon configuration, the init system
c1621f589e6e26efc55db89e59c9f445580856cctrawick installs the sockets and then hands them off
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun to the spawned process as soon as the
c1621f589e6e26efc55db89e59c9f445580856cctrawick respective daemon is to be started.
4a7be288e6fc28a6cb940e26542dbf574bc907b9pctony Optionally, activation of the service can be
c1621f589e6e26efc55db89e59c9f445580856cctrawick delayed until the first inbound traffic
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi arrives at the socket to implement on-demand
c1621f589e6e26efc55db89e59c9f445580856cctrawick activation of daemons. However, the primary
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi advantage of this scheme is that all providers
c1621f589e6e26efc55db89e59c9f445580856cctrawick and all consumers of the sockets can be
c1621f589e6e26efc55db89e59c9f445580856cctrawick started in parallel as soon as all sockets
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi are established. In addition to that, daemons
c1621f589e6e26efc55db89e59c9f445580856cctrawick can be restarted with losing only a minimal
c1621f589e6e26efc55db89e59c9f445580856cctrawick number of client transactions, or even any
c1621f589e6e26efc55db89e59c9f445580856cctrawick client request at all (the latter is
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end particularly true for state-less protocols,
c1621f589e6e26efc55db89e59c9f445580856cctrawick such as DNS or syslog), because the socket
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end stays bound and accessible during the restart,
c1621f589e6e26efc55db89e59c9f445580856cctrawick and all requests are queued while the daemon
c1621f589e6e26efc55db89e59c9f445580856cctrawick cannot process them.</para>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <para>New-style daemons which support socket
c1621f589e6e26efc55db89e59c9f445580856cctrawick activation must be able to receive their
c1621f589e6e26efc55db89e59c9f445580856cctrawick sockets from the init system instead of
c1621f589e6e26efc55db89e59c9f445580856cctrawick creating and binding them themselves. For
c1621f589e6e26efc55db89e59c9f445580856cctrawick details about the programming interfaces for
31f98e851c108552a628e32c39e4c3e7a62394d5nd this scheme provided by systemd, see
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. For
c1621f589e6e26efc55db89e59c9f445580856cctrawick details about porting existing daemons to
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi socket-based activation, see below. With
c1621f589e6e26efc55db89e59c9f445580856cctrawick minimal effort, it is possible to implement
c1621f589e6e26efc55db89e59c9f445580856cctrawick socket-based activation in addition to
c1621f589e6e26efc55db89e59c9f445580856cctrawick traditional internal socket creation in the
c1621f589e6e26efc55db89e59c9f445580856cctrawick same codebase in order to support both
c1621f589e6e26efc55db89e59c9f445580856cctrawick new-style and old-style init systems from the
c1621f589e6e26efc55db89e59c9f445580856cctrawick same daemon binary.</para>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <para>systemd implements socket-based
c1621f589e6e26efc55db89e59c9f445580856cctrawick units, which are described in
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. When
c1621f589e6e26efc55db89e59c9f445580856cctrawick configuring socket units for socket-based
c1621f589e6e26efc55db89e59c9f445580856cctrawick activation, it is essential that all listening
c1621f589e6e26efc55db89e59c9f445580856cctrawick sockets are pulled in by the special target
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end is recommended to place a
c1621f589e6e26efc55db89e59c9f445580856cctrawick section to automatically add such a
c1621f589e6e26efc55db89e59c9f445580856cctrawick dependency on installation of a socket
c1621f589e6e26efc55db89e59c9f445580856cctrawick unit. Unless
c1621f589e6e26efc55db89e59c9f445580856cctrawick set, the necessary ordering dependencies are
c1621f589e6e26efc55db89e59c9f445580856cctrawick implicitly created for all socket units. For
01d52afd5ea497df24826737569291294d5dfa04rbowen more information about
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. It
c1621f589e6e26efc55db89e59c9f445580856cctrawick is not necessary or recommended to place any
f3ec420152ca921e4c1ce77782f51b53f659018dnd additional dependencies on socket units (for
c1621f589e6e26efc55db89e59c9f445580856cctrawick example from
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar suchlike) when one is installed in
c1621f589e6e26efc55db89e59c9f445580856cctrawick </refsect2>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <para>When the D-Bus IPC system is used for
c1621f589e6e26efc55db89e59c9f445580856cctrawick communication with clients, new-style daemons
c1621f589e6e26efc55db89e59c9f445580856cctrawick should employ bus activation so that they are
c1621f589e6e26efc55db89e59c9f445580856cctrawick automatically activated when a client
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi application accesses their IPC
c1621f589e6e26efc55db89e59c9f445580856cctrawick interfaces. This is configured in D-Bus
c1621f589e6e26efc55db89e59c9f445580856cctrawick service files (not to be confused with systemd
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi service unit files!). To ensure that D-Bus
c1621f589e6e26efc55db89e59c9f445580856cctrawick uses systemd to start-up and maintain the
c1621f589e6e26efc55db89e59c9f445580856cctrawick daemon, use the
c1621f589e6e26efc55db89e59c9f445580856cctrawick in these service files to configure the
c1621f589e6e26efc55db89e59c9f445580856cctrawick matching systemd service for a D-Bus
c1621f589e6e26efc55db89e59c9f445580856cctrawick service. e.g.: For a D-Bus service whose D-Bus
c1621f589e6e26efc55db89e59c9f445580856cctrawick activation file is named
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <filename>org.freedesktop.RealtimeKit.service</filename>,
c1621f589e6e26efc55db89e59c9f445580856cctrawick make sure to set
c1621f589e6e26efc55db89e59c9f445580856cctrawick in that file to bind it to the systemd
c1621f589e6e26efc55db89e59c9f445580856cctrawick is needed to make sure that the daemon is
c1621f589e6e26efc55db89e59c9f445580856cctrawick started in a race-free fashion when activated
dfc5f686a6ac416a480f0281c9ff0a751013fcf2nilgun via multiple mechanisms simultaneously.</para>
c1621f589e6e26efc55db89e59c9f445580856cctrawick </refsect2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <para>Often, daemons that manage a particular
c1621f589e6e26efc55db89e59c9f445580856cctrawick type of hardware should be activated only when
f3ec420152ca921e4c1ce77782f51b53f659018dnd the hardware of the respective kind is plugged
c1621f589e6e26efc55db89e59c9f445580856cctrawick in or otherwise becomes available. In a
c1621f589e6e26efc55db89e59c9f445580856cctrawick new-style init system, it is possible to bind
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end systemd, kernel devices appearing in the
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end if they are tagged with the string
c1621f589e6e26efc55db89e59c9f445580856cctrawick kind of unit, they may then pull in other units
c1621f589e6e26efc55db89e59c9f445580856cctrawick when activated (i.e. plugged in) and thus
c1621f589e6e26efc55db89e59c9f445580856cctrawick implement device-based activation. systemd
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end dependencies may be encoded in the udev
c1621f589e6e26efc55db89e59c9f445580856cctrawick database via the
c1621f589e6e26efc55db89e59c9f445580856cctrawick property. See
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
c1621f589e6e26efc55db89e59c9f445580856cctrawick for details. Often, it is nicer to pull in
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi services from devices only indirectly via
c1621f589e6e26efc55db89e59c9f445580856cctrawick dedicated targets. Example: Instead of pulling
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi from all the various bluetooth dongles and
c1621f589e6e26efc55db89e59c9f445580856cctrawick other hardware available, pull in
c1621f589e6e26efc55db89e59c9f445580856cctrawick that target. This provides for nicer
c1621f589e6e26efc55db89e59c9f445580856cctrawick abstraction and gives administrators the
c1621f589e6e26efc55db89e59c9f445580856cctrawick option to enable
c1621f589e6e26efc55db89e59c9f445580856cctrawick controlling a
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end symlink uniformly with a command like
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
c1621f589e6e26efc55db89e59c9f445580856cctrawick instead of manipulating the udev
c1621f589e6e26efc55db89e59c9f445580856cctrawick ruleset.</para>
c1621f589e6e26efc55db89e59c9f445580856cctrawick </refsect2>
c1621f589e6e26efc55db89e59c9f445580856cctrawick <para>Often, runtime of daemons processing
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end spool files or directories (such as a printing
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end system) can be delayed until these file system
c1621f589e6e26efc55db89e59c9f445580856cctrawick objects change state, or become
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end non-empty. New-style init systems provide a
c1621f589e6e26efc55db89e59c9f445580856cctrawick way to bind service activation to file system
c1621f589e6e26efc55db89e59c9f445580856cctrawick changes. systemd implements this scheme via
c1621f589e6e26efc55db89e59c9f445580856cctrawick path-based activation configured in
c1621f589e6e26efc55db89e59c9f445580856cctrawick <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
c1621f589e6e26efc55db89e59c9f445580856cctrawick </refsect2>
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi <para>Some daemons that implement clean-up
c1621f589e6e26efc55db89e59c9f445580856cctrawick jobs that are intended to be executed in
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi regular intervals benefit from timer-based
c1621f589e6e26efc55db89e59c9f445580856cctrawick activation. In systemd, this is implemented
c1621f589e6e26efc55db89e59c9f445580856cctrawick described in
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
c1621f589e6e26efc55db89e59c9f445580856cctrawick </refsect2>
1723928efa40774afc394d9e6b2b974c1f49330dnd <para>Other forms of activation have been
1723928efa40774afc394d9e6b2b974c1f49330dnd suggested and implemented in some
1723928efa40774afc394d9e6b2b974c1f49330dnd systems. However, there are often simpler or
f3ec420152ca921e4c1ce77782f51b53f659018dnd better alternatives, or they can be put
1723928efa40774afc394d9e6b2b974c1f49330dnd together of combinations of the schemes
f3ec420152ca921e4c1ce77782f51b53f659018dnd above. Example: Sometimes, it appears useful to
1723928efa40774afc394d9e6b2b974c1f49330dnd units when a specific IP address is configured
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi on a network interface, because network
1723928efa40774afc394d9e6b2b974c1f49330dnd sockets shall be bound to the
1723928efa40774afc394d9e6b2b974c1f49330dnd address. However, an alternative to implement
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi this is by utilizing the Linux IP_FREEBIND
1723928efa40774afc394d9e6b2b974c1f49330dnd socket option, as accessible via
45a544a8bb3fa1f95e5edac9fb3e723e2bb7001drbowen socket files (see
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen for details). This option, when enabled,
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun allows sockets to be bound to a non-local, not
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen configured IP address, and hence allows
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen bindings to a particular IP address before it
e83cd73f10044371dd9dfa5f46b6d7d5c585fe54sf actually becomes available, making such an
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen explicit dependency to the configured address
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen redundant. Another often suggested trigger for
49acc6accb4061182ef84dc991aaa346ad01a8ecsf service activation is low system
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen load. However, here too, a more convincing
c819c19c2f1ffbf3a3f12a4070cc6c3f4ea2a6f2sf approach might be to make proper use of
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen features of the operating system, in
cef8c32664f99ed33838dd0bde26051c4b71af1bsf particular, the CPU or IO scheduler of
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen Linux. Instead of scheduling jobs from
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen userspace based on monitoring the OS
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen scheduler, it is advisable to leave the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen scheduling of processes to the OS scheduler
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen itself. systemd provides fine-grained access
4ed26c413f67a5aae20b95909828f30bb5dc2286poirier to the CPU and IO schedulers. If a process
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen executed by the init system shall not
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen negatively impact the amount of CPU or IO
63befe0983261d711e62457b380e24ecc3b7b79etrawick bandwidth available to other processes, it
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen should be configured with
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <varname>IOSchedulingClass=idle</varname>. Optionally,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen this may be combined with timer-based
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen activation to schedule background jobs during
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen runtime and with minimal impact on the system,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen and remove it from the boot phase
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen itself.</para>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen </refsect2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen </refsect1>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>When writing systemd unit files, it is
4a7be288e6fc28a6cb940e26542dbf574bc907b9pctony recommended to consider the following
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen suggestions:</para>
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun <orderedlist>
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun setting in service files. But if you
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen do, make sure to set the PID file path
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen registers a D-Bus name on the bus,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen make sure to use
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen service file if
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end good human-readable description string
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen unless you really know what you do and
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end your unit is involved in early boot or
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen any dependencies should need to
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen be defined explicitly. However, if you
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen do configure explicit dependencies, only refer to
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end unit names listed on
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen or names introduced by your own
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen package to keep the unit file
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen section including installation
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen information for the unit file. See
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen for details. To activate your service
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen on boot, make sure to add a
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen directive. To activate your socket on
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen boot, make sure to add
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen you also want to make sure that when
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen your service is installed, your socket
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen is installed too, hence add
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen your service file
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen a hypothetical program
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen </orderedlist>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen </refsect2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>At the build installation time
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen package build), packages are recommended to
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen install their systemd unit files in the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen directory returned by <command>pkg-config
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen --variable=systemdsystemunitdir</command> (for
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen system services) or <command>pkg-config
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen --variable=systemduserunitdir</command>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen (for user services). This will make the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen services available in the system on explicit
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen request but not activate them automatically
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen during boot. Optionally, during package
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen by the administrator), symlinks should be
4126704c4950bfd46d32ad54e3b106ac6d868a73sf created in the systemd configuration
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen command of the
01d52afd5ea497df24826737569291294d5dfa04rbowen <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
01d52afd5ea497df24826737569291294d5dfa04rbowen tool to activate them automatically on
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen boot.</para>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>Packages using
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
4126704c4950bfd46d32ad54e3b106ac6d868a73sf are recommended to use a configure script
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen excerpt like the following to determine the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen unit installation path during source
4126704c4950bfd46d32ad54e3b106ac6d868a73sf configuration:</para>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <programlisting>PKG_PROG_PKG_CONFIG
cc094350da96eecbed411d410393716ada05c402igalicAC_ARG_WITH([systemdsystemunitdir],
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenif test "x$with_systemdsystemunitdir" != xno; then
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenAM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ])</programlisting>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>This snippet allows automatic
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen installation of the unit files on systemd
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen machines, and optionally allows their
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen installation even on machines lacking
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen systemd. (Modification of this snippet for the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen user unit directory is left as an exercise for the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen reader.)</para>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <para>Additionally, to ensure that
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen work, it is recommended to add the following
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end projects:</para>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <programlisting>if HAVE_SYSTEMD
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowensystemdsystemunit_DATA = \
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenendif</programlisting>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>In the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen service during
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen the RPM macros shipped along systemd. Consult
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen the packaging guidelines of your distribution
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen for details and the equivalent for other
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen package managers.</para>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <programlisting>BuildRequires: systemd
1ac39787115a288f5e848344b1b1e8dccb1c58f1nd%{?systemd_requires}</programlisting>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <programlisting>%post
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen%systemd_postun</programlisting>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>If the service shall be restarted during
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen upgrades, replace the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen with the following:</para>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <programlisting>%postun
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen%systemd_postun_with_restart foobar.service</programlisting>
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end <para>Note that
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen as arguments, separated by
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end expects no
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen arguments. <literal>%systemd_postun_with_restart</literal>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen expects the units to restart as
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end arguments.</para>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>To facilitate upgrades from a package
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end version that shipped only SysV init scripts to
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen a package version that ships both a SysV init
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen script and a native systemd service file, use
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end a fragment like the following:</para>
01d52afd5ea497df24826737569291294d5dfa04rbowen <programlisting>%triggerun -- foobar < 0.47.11-1
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || :
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowenfi</programlisting>
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf <para>Where 0.47.11-1 is the first package
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen version that includes the native unit
11495c9f0bd33e51a25b4d532beadfbcf9b944a3nilgun file. This fragment will ensure that the first
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen time the unit file is installed, it will be
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen enabled if and only if the SysV init script is
cd6c8de3bedcc401ee230159b0439fa20f44488etakashi enabled, thus making sure that the enable
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen status is not changed. Note that
d0828c8a321dc5e9ea60550f052294669c08cf93jim specific to Fedora which can be used to check
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen whether a SysV init script is enabled. Other
d0828c8a321dc5e9ea60550f052294669c08cf93jim operating systems will have to use different
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen commands here.</para>
d0828c8a321dc5e9ea60550f052294669c08cf93jim </refsect2>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen </refsect1>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <para>Since new-style init systems such as systemd are
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen compatible with traditional SysV init systems, it is
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen not strictly necessary to port existing daemons to the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen new style. However, doing so offers additional
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen functionality to the daemons as well as simplifying
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen integration into new-style init systems.</para>
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun <para>To port an existing SysV compatible daemon, the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen following steps are recommended:</para>
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun <orderedlist>
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun add an optional command line switch to the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen daemon to disable daemonization. This is
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end useful not only for using the daemon in
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen new-style init systems, but also to ease
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen interfaces to other software running on the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen local system via local <constant>AF_UNIX</constant> sockets,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen consider implementing socket-based activation
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen (see above). Usually, a minimal patch is
1ac39787115a288f5e848344b1b1e8dccb1c58f1nd sufficient to implement this: Extend the
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen socket creation in the daemon code so that
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen is checked for already passed sockets
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end first. If sockets are passed (i.e. when
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen positive value), skip the socket creation step
63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end and use the passed sockets. Secondly, ensure
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen that the file system socket nodes for local
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <constant>AF_UNIX</constant> sockets used in the socket-based
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen activation are not removed when the daemon
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun shuts down, if sockets have been
b9bf3918f6eaf7747bcbfbd02792bcbe4a052784nilgun passed. Third, if the daemon normally closes
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen all remaining open file descriptors as part of
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen its initialization, the sockets passed from
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi the init system must be spared. Since
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen new-style init systems guarantee that no
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi left-over file descriptors are passed to
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi executed processes, it might be a good choice
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen to simply skip the closing of all remaining
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen open file descriptors if sockets are
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen unit file for the service (and the sockets if
0237f43ab925775250e266e479d0a337ff374a4btakashi socket-based activation is used, as well as a
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen path unit file, if the daemon processes a
0237f43ab925775250e266e479d0a337ff374a4btakashi spool directory), see above for
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen interfaces via D-Bus, write and install a
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen D-Bus activation file for the service, see
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen </orderedlist>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen </refsect1>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f772e8f448c223e5ea306f1bf92d97d968f972d5jim <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
0bd1ddab48139fbbe68f4e257fe669dc19f58fe9rbowen </refsect1>