mirror of
https://git.proxmox.com/git/systemd
synced 2026-01-13 19:14:49 +00:00
689 lines
52 KiB
HTML
689 lines
52 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>daemon</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
|
|
a.headerlink {
|
|
color: #c60f0f;
|
|
font-size: 0.8em;
|
|
padding: 0 4px 0 4px;
|
|
text-decoration: none;
|
|
visibility: hidden;
|
|
}
|
|
|
|
a.headerlink:hover {
|
|
background-color: #c60f0f;
|
|
color: white;
|
|
}
|
|
|
|
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
|
|
visibility: visible;
|
|
}
|
|
</style><a href="index.html">Index </a>·
|
|
<a href="systemd.directives.html">Directives </a>·
|
|
<a href="../python-systemd/index.html">Python </a>·
|
|
<a href="../libudev/index.html">libudev </a>·
|
|
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 208</span><hr><div class="refentry"><a name="daemon"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>daemon — Writing and packaging system daemons</p></div><div class="refsect1"><a name="idm274686553024"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>A daemon is a service process that runs in the
|
|
background and supervises the system or provides
|
|
functionality to other processes. Traditionally,
|
|
daemons are implemented following a scheme originating
|
|
in SysV Unix. Modern daemons should follow a simpler
|
|
yet more powerful scheme (here called "new-style"
|
|
daemons), as implemented by
|
|
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>. This
|
|
manual page covers both schemes, and in
|
|
particular includes recommendations for daemons that
|
|
shall be included in the systemd init system.</p><div class="refsect2"><a name="idm274687502064"></a><h3 id="SysV Daemons">SysV Daemons<a class="headerlink" title="Permalink to this headline" href="#SysV%20Daemons">¶</a></h3><p>When a traditional SysV daemon
|
|
starts, it should execute the following steps
|
|
as part of the initialization. Note that these
|
|
steps are unnecessary for new-style daemons (see below),
|
|
and should only be implemented if compatibility
|
|
with SysV is essential.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Close all open file
|
|
descriptors except STDIN, STDOUT,
|
|
STDERR (i.e. the first three file
|
|
descriptors 0, 1, 2). This ensures
|
|
that no accidentally passed file
|
|
descriptor stays around in the daemon
|
|
process. On Linux, this is best
|
|
implemented by iterating through
|
|
<code class="filename">/proc/self/fd</code>,
|
|
with a fallback of iterating from file
|
|
descriptor 3 to the value returned by
|
|
<code class="function">getrlimit()</code> for
|
|
RLIMIT_NOFILE.</p></li><li class="listitem"><p>Reset all signal
|
|
handlers to their default. This is
|
|
best done by iterating through the
|
|
available signals up to the limit of
|
|
_NSIG and resetting them to
|
|
<code class="constant">SIG_DFL</code>.</p></li><li class="listitem"><p>Reset the signal mask
|
|
using
|
|
<code class="function">sigprocmask()</code>.</p></li><li class="listitem"><p>Sanitize the
|
|
environment block, removing or
|
|
resetting environment variables that
|
|
might negatively impact daemon
|
|
runtime.</p></li><li class="listitem"><p>Call <code class="function">fork()</code>,
|
|
to create a background
|
|
process.</p></li><li class="listitem"><p>In the child, call
|
|
<code class="function">setsid()</code> to
|
|
detach from any terminal and create an
|
|
independent session.</p></li><li class="listitem"><p>In the child, call
|
|
<code class="function">fork()</code> again, to
|
|
ensure that the daemon can never re-acquire
|
|
a terminal again.</p></li><li class="listitem"><p>Call <code class="function">exit()</code> in the
|
|
first child, so that only the second
|
|
child (the actual daemon process)
|
|
stays around. This ensures that the
|
|
daemon process is re-parented to
|
|
init/PID 1, as all daemons should
|
|
be.</p></li><li class="listitem"><p>In the daemon process,
|
|
connect <code class="filename">/dev/null</code>
|
|
to STDIN, STDOUT,
|
|
STDERR.</p></li><li class="listitem"><p>In the daemon process,
|
|
reset the umask to 0, so that the file
|
|
modes passed to <code class="function">open()</code>, <code class="function">mkdir()</code> and
|
|
suchlike directly control the access
|
|
mode of the created files and
|
|
directories.</p></li><li class="listitem"><p>In the daemon process,
|
|
change the current directory to the
|
|
root directory (/), in order to avoid
|
|
that the daemon involuntarily
|
|
blocks mount points from being
|
|
unmounted.</p></li><li class="listitem"><p>In the daemon process,
|
|
write the daemon PID (as returned by
|
|
<code class="function">getpid()</code>) to a
|
|
PID file, for example
|
|
<code class="filename">/var/run/foobar.pid</code>
|
|
(for a hypothetical daemon "foobar")
|
|
to ensure that the daemon cannot be
|
|
started more than once. This must be
|
|
implemented in race-free fashion so
|
|
that the PID file is only updated when
|
|
it is verified at the same time that
|
|
the PID previously stored in the PID
|
|
file no longer exists or belongs to a
|
|
foreign process. Commonly, some kind of
|
|
file locking is employed to implement
|
|
this logic.</p></li><li class="listitem"><p>In the daemon process,
|
|
drop privileges, if possible and
|
|
applicable.</p></li><li class="listitem"><p>From the daemon
|
|
process, notify the original process
|
|
started that initialization is
|
|
complete. This can be implemented via
|
|
an unnamed pipe or similar
|
|
communication channel that is created
|
|
before the first
|
|
<code class="function">fork()</code> and hence
|
|
available in both the original and the
|
|
daemon process.</p></li><li class="listitem"><p>Call
|
|
<code class="function">exit()</code> in the
|
|
original process. The process that
|
|
invoked the daemon must be able to
|
|
rely on that this
|
|
<code class="function">exit()</code> happens
|
|
after initialization is complete and
|
|
all external communication channels
|
|
are established and
|
|
accessible.</p></li></ol></div><p>The BSD <code class="function">daemon()</code> function should not be
|
|
used, as it implements only a subset of these steps.</p><p>A daemon that needs to provide
|
|
compatibility with SysV systems should
|
|
implement the scheme pointed out
|
|
above. However, it is recommended to make this
|
|
behavior optional and configurable via a
|
|
command line argument to ease debugging as
|
|
well as to simplify integration into systems
|
|
using systemd.</p></div><div class="refsect2"><a name="idm274689046528"></a><h3 id="New-Style Daemons">New-Style Daemons<a class="headerlink" title="Permalink to this headline" href="#New-Style%20Daemons">¶</a></h3><p>Modern services for Linux should be
|
|
implemented as new-style daemons. This makes it
|
|
easier to supervise and control them at
|
|
runtime and simplifies their
|
|
implementation.</p><p>For developing a new-style daemon, none
|
|
of the initialization steps recommended for
|
|
SysV daemons need to be implemented. New-style
|
|
init systems such as systemd make all of them
|
|
redundant. Moreover, since some of these steps
|
|
interfere with process monitoring, file
|
|
descriptor passing and other functionality of
|
|
the init system, it is recommended not to
|
|
execute them when run as new-style
|
|
service.</p><p>Note that new-style init systems
|
|
guarantee execution of daemon processes in
|
|
a clean process context: it is guaranteed that
|
|
the environment block is sanitized, that the
|
|
signal handlers and mask is reset and that no
|
|
left-over file descriptors are passed. Daemons
|
|
will be executed in their own session, and
|
|
STDIN/STDOUT/STDERR connected to
|
|
<code class="filename">/dev/null</code> unless
|
|
otherwise configured. The umask is reset.</p><p>It is recommended for new-style daemons
|
|
to implement the following:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>If <code class="constant">SIGTERM</code> is
|
|
received, shut down the daemon and
|
|
exit cleanly.</p></li><li class="listitem"><p>If <code class="constant">SIGHUP</code> is received,
|
|
reload the configuration files, if
|
|
this applies.</p></li><li class="listitem"><p>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 <a class="ulink" href="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html" target="_top">LSB
|
|
recommendations for SysV init
|
|
scripts</a>.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>For integration in
|
|
systemd, provide a
|
|
<code class="filename">.service</code> unit
|
|
file that carries information about
|
|
starting, stopping and otherwise
|
|
maintaining the daemon. See
|
|
<a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
|
|
for details.</p></li><li class="listitem"><p>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
|
|
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>
|
|
for the available
|
|
controls.</p></li><li class="listitem"><p>If D-Bus is used, make
|
|
your daemon bus-activatable by
|
|
supplying a D-Bus service activation
|
|
configuration file. This has multiple
|
|
advantages: your daemon may be started
|
|
lazily on-demand; it may be started in
|
|
parallel to other daemons requiring it
|
|
-- which maximizes parallelization and
|
|
boot-up speed; your daemon can be
|
|
restarted on failure without losing
|
|
any bus requests, as the bus queues
|
|
requests for activatable services. See
|
|
below for details.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>If applicable, a daemon
|
|
should notify the init system about
|
|
startup completion or status updates
|
|
via the
|
|
<a href="sd_notify.html"><span class="citerefentry"><span class="refentrytitle">sd_notify</span>(3)</span></a>
|
|
interface.</p></li><li class="listitem"><p>Instead of using the
|
|
<code class="function">syslog()</code> call to log directly to the
|
|
system syslog service, a new-style daemon may
|
|
choose to simply log to STDERR via
|
|
<code class="function">fprintf()</code>, 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 "<4>"
|
|
(for log priority 4 "WARNING" in the
|
|
syslog priority scheme), following a
|
|
similar style as the Linux kernel's
|
|
<code class="function">printk()</code> 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
|
|
<a href="dmesg.html"><span class="citerefentry"><span class="refentrytitle">dmesg</span>(1)</span></a>. This
|
|
kind of logging may be enabled by
|
|
setting
|
|
<code class="varname">StandardError=syslog</code>
|
|
in the service unit file. For details,
|
|
see
|
|
<a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>
|
|
and
|
|
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>.</p></li></ol></div><p>These recommendations are similar but
|
|
not identical to the <a class="ulink" href="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738" target="_top">Apple
|
|
MacOS X Daemon Requirements</a>.</p></div></div><div class="refsect1"><a name="idm274689010544"></a><h2 id="Activation">Activation<a class="headerlink" title="Permalink to this headline" href="#Activation">¶</a></h2><p>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:
|
|
<code class="filename">bluetoothd.service</code> 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.</p><div class="refsect2"><a name="idm274689007216"></a><h3 id="Activation on Boot">Activation on Boot<a class="headerlink" title="Permalink to this headline" href="#Activation%20on%20Boot">¶</a></h3><p>Old-style daemons are usually activated
|
|
exclusively on boot (and manually by the
|
|
administrator) via SysV init scripts, as
|
|
detailed in the <a class="ulink" href="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html" target="_top">LSB
|
|
Linux Standard Base Core
|
|
Specification</a>. 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.</p><p>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 <code class="filename">.wants/</code>
|
|
directory of either
|
|
<code class="filename">multi-user.target</code> or
|
|
<code class="filename">graphical.target</code>, which
|
|
are normally used as boot targets at system
|
|
startup. See
|
|
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
|
|
for details about the
|
|
<code class="filename">.wants/</code> directories, and
|
|
<a href="systemd.special.html"><span class="citerefentry"><span class="refentrytitle">systemd.special</span>(7)</span></a>
|
|
for details about the two boot targets.</p></div><div class="refsect2"><a name="idm274684370608"></a><h3 id="Socket-Based Activation">Socket-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Socket-Based%20Activation">¶</a></h3><p>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.</p><p>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
|
|
<a href="sd_listen_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_listen_fds</span>(3)</span></a>
|
|
and
|
|
<a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>. 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.</p><p>systemd implements socket-based
|
|
activation via <code class="filename">.socket</code>
|
|
units, which are described in
|
|
<a href="systemd.socket.html"><span class="citerefentry"><span class="refentrytitle">systemd.socket</span>(5)</span></a>. When
|
|
configuring socket units for socket-based
|
|
activation, it is essential that all listening
|
|
sockets are pulled in by the special target
|
|
unit <code class="filename">sockets.target</code>. It
|
|
is recommended to place a
|
|
<code class="varname">WantedBy=sockets.target</code>
|
|
directive in the "<code class="literal">[Install]</code>"
|
|
section to automatically add such a
|
|
dependency on installation of a socket
|
|
unit. Unless
|
|
<code class="varname">DefaultDependencies=no</code> is
|
|
set, the necessary ordering dependencies are
|
|
implicitly created for all socket units. For
|
|
more information about
|
|
<code class="filename">sockets.target</code>, see
|
|
<a href="systemd.special.html"><span class="citerefentry"><span class="refentrytitle">systemd.special</span>(7)</span></a>. It
|
|
is not necessary or recommended to place any
|
|
additional dependencies on socket units (for
|
|
example from
|
|
<code class="filename">multi-user.target</code> or
|
|
suchlike) when one is installed in
|
|
<code class="filename">sockets.target</code>.</p></div><div class="refsect2"><a name="idm274684357232"></a><h3 id="Bus-Based Activation">Bus-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Bus-Based%20Activation">¶</a></h3><p>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
|
|
<code class="varname">SystemdService=</code> 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
|
|
<code class="filename">org.freedesktop.RealtimeKit.service</code>,
|
|
make sure to set
|
|
<code class="varname">SystemdService=rtkit-daemon.service</code>
|
|
in that file to bind it to the systemd
|
|
service
|
|
<code class="filename">rtkit-daemon.service</code>. This
|
|
is needed to make sure that the daemon is
|
|
started in a race-free fashion when activated
|
|
via multiple mechanisms simultaneously.</p></div><div class="refsect2"><a name="idm274684352752"></a><h3 id="Device-Based Activation">Device-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Device-Based%20Activation">¶</a></h3><p>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
|
|
"<code class="literal">systemd</code>". 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
|
|
<code class="varname">SYSTEMD_WANTS=</code>
|
|
property. See
|
|
<a href="systemd.device.html"><span class="citerefentry"><span class="refentrytitle">systemd.device</span>(5)</span></a>
|
|
for details. Often, it is nicer to pull in
|
|
services from devices only indirectly via
|
|
dedicated targets. Example: Instead of pulling
|
|
in <code class="filename">bluetoothd.service</code>
|
|
from all the various bluetooth dongles and
|
|
other hardware available, pull in
|
|
bluetooth.target from them and
|
|
<code class="filename">bluetoothd.service</code> from
|
|
that target. This provides for nicer
|
|
abstraction and gives administrators the
|
|
option to enable
|
|
<code class="filename">bluetoothd.service</code> via
|
|
controlling a
|
|
<code class="filename">bluetooth.target.wants/</code>
|
|
symlink uniformly with a command like
|
|
<span class="command"><strong>enable</strong></span> of
|
|
<a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>
|
|
instead of manipulating the udev
|
|
ruleset.</p></div><div class="refsect2"><a name="idm274684343888"></a><h3 id="Path-Based Activation">Path-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Path-Based%20Activation">¶</a></h3><p>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
|
|
<code class="filename">.path</code> units, as outlined
|
|
in
|
|
<a href="systemd.path.html"><span class="citerefentry"><span class="refentrytitle">systemd.path</span>(5)</span></a>.</p></div><div class="refsect2"><a name="idm274684340720"></a><h3 id="Timer-Based Activation">Timer-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Timer-Based%20Activation">¶</a></h3><p>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 <code class="filename">.timer</code> units, as
|
|
described in
|
|
<a href="systemd.timer.html"><span class="citerefentry"><span class="refentrytitle">systemd.timer</span>(5)</span></a>.</p></div><div class="refsect2"><a name="idm274684337792"></a><h3 id="Other Forms of Activation">Other Forms of Activation<a class="headerlink" title="Permalink to this headline" href="#Other%20Forms%20of%20Activation">¶</a></h3><p>Other forms of activation have been
|
|
suggested and implemented in some
|
|
systems. However, there are often simpler or
|
|
better alternatives, or they can be put
|
|
together of combinations of the schemes
|
|
above. Example: Sometimes, it appears useful to
|
|
start daemons or <code class="filename">.socket</code>
|
|
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
|
|
<code class="varname">FreeBind=yes</code> in systemd
|
|
socket files (see
|
|
<a href="systemd.socket.html"><span class="citerefentry"><span class="refentrytitle">systemd.socket</span>(5)</span></a>
|
|
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
|
|
<code class="varname">CPUSchedulingPolicy=idle</code>
|
|
and/or
|
|
<code class="varname">IOSchedulingClass=idle</code>. 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.</p></div></div><div class="refsect1"><a name="idm274689114736"></a><h2 id="Integration with Systemd">Integration with Systemd<a class="headerlink" title="Permalink to this headline" href="#Integration%20with%20Systemd">¶</a></h2><div class="refsect2"><a name="idm274689114048"></a><h3 id="Writing Systemd Unit Files">Writing Systemd Unit Files<a class="headerlink" title="Permalink to this headline" href="#Writing%20Systemd%20Unit%20Files">¶</a></h3><p>When writing systemd unit files, it is
|
|
recommended to consider the following
|
|
suggestions:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>If possible, do not use
|
|
the <code class="varname">Type=forking</code>
|
|
setting in service files. But if you
|
|
do, make sure to set the PID file path
|
|
using <code class="varname">PIDFile=</code>. See
|
|
<a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
|
|
for details.</p></li><li class="listitem"><p>If your daemon
|
|
registers a D-Bus name on the bus,
|
|
make sure to use
|
|
<code class="varname">Type=dbus</code> in the
|
|
service file if
|
|
possible.</p></li><li class="listitem"><p>Make sure to set a
|
|
good human-readable description string
|
|
with
|
|
<code class="varname">Description=</code>.</p></li><li class="listitem"><p>Do not disable
|
|
<code class="varname">DefaultDependencies=</code>,
|
|
unless you really know what you do and
|
|
your unit is involved in early boot or
|
|
late system shutdown.</p></li><li class="listitem"><p>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
|
|
<a href="systemd.special.html"><span class="citerefentry"><span class="refentrytitle">systemd.special</span>(7)</span></a>
|
|
or names introduced by your own
|
|
package to keep the unit file
|
|
operating
|
|
system-independent.</p></li><li class="listitem"><p>Make sure to include
|
|
an "<code class="literal">[Install]</code>"
|
|
section including installation
|
|
information for the unit file. See
|
|
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
|
|
for details. To activate your service
|
|
on boot, make sure to add a
|
|
<code class="varname">WantedBy=multi-user.target</code>
|
|
or
|
|
<code class="varname">WantedBy=graphical.target</code>
|
|
directive. To activate your socket on
|
|
boot, make sure to add
|
|
<code class="varname">WantedBy=sockets.target</code>. Usually,
|
|
you also want to make sure that when
|
|
your service is installed, your socket
|
|
is installed too, hence add
|
|
<code class="varname">Also=foo.socket</code> in
|
|
your service file
|
|
<code class="filename">foo.service</code>, for
|
|
a hypothetical program
|
|
<code class="filename">foo</code>.</p></li></ol></div></div><div class="refsect2"><a name="idm274684306432"></a><h3 id="Installing Systemd Service Files">Installing Systemd Service Files<a class="headerlink" title="Permalink to this headline" href="#Installing%20Systemd%20Service%20Files">¶</a></h3><p>At the build installation time
|
|
(e.g. <span class="command"><strong>make install</strong></span> during
|
|
package build), packages are recommended to
|
|
install their systemd unit files in the
|
|
directory returned by <span class="command"><strong>pkg-config
|
|
systemd
|
|
--variable=systemdsystemunitdir</strong></span> (for
|
|
system services) or <span class="command"><strong>pkg-config
|
|
systemd
|
|
--variable=systemduserunitdir</strong></span>
|
|
(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. <span class="command"><strong>rpm -i</strong></span>
|
|
by the administrator), symlinks should be
|
|
created in the systemd configuration
|
|
directories via the <span class="command"><strong>enable</strong></span>
|
|
command of the
|
|
<a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>
|
|
tool to activate them automatically on
|
|
boot.</p><p>Packages using
|
|
<a href="autoconf.html"><span class="citerefentry"><span class="refentrytitle">autoconf</span>(1)</span></a>
|
|
are recommended to use a configure script
|
|
excerpt like the following to determine the
|
|
unit installation path during source
|
|
configuration:</p><pre class="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 ])</pre><p>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.)</p><p>Additionally, to ensure that
|
|
<span class="command"><strong>make distcheck</strong></span> continues to
|
|
work, it is recommended to add the following
|
|
to the top-level <code class="filename">Makefile.am</code>
|
|
file in
|
|
<a href="automake.html"><span class="citerefentry"><span class="refentrytitle">automake</span>(1)</span></a>-based
|
|
projects:</p><pre class="programlisting">DISTCHECK_CONFIGURE_FLAGS = \
|
|
--with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</pre><p>Finally, unit files should be installed in the system with an automake excerpt like the following:</p><pre class="programlisting">if HAVE_SYSTEMD
|
|
systemdsystemunit_DATA = \
|
|
foobar.socket \
|
|
foobar.service
|
|
endif</pre><p>In the
|
|
<a href="rpm.html"><span class="citerefentry"><span class="refentrytitle">rpm</span>(8)</span></a>
|
|
<code class="filename">.spec</code> 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.</p><p>At the top of the file:</p><pre class="programlisting">BuildRequires: systemd
|
|
%{?systemd_requires}</pre><p>And as scriptlets, further down:</p><pre class="programlisting">%post
|
|
%systemd_post foobar.service foobar.socket
|
|
|
|
%preun
|
|
%systemd_preun foobar.service foobar.socket
|
|
|
|
%postun
|
|
%systemd_postun</pre><p>If the service shall be restarted during
|
|
upgrades, replace the
|
|
"<code class="literal">%postun</code>" scriptlet above
|
|
with the following:</p><pre class="programlisting">%postun
|
|
%systemd_postun_with_restart foobar.service</pre><p>Note that
|
|
"<code class="literal">%systemd_post</code>" and
|
|
"<code class="literal">%systemd_preun</code>" expect the
|
|
names of all units that are installed/removed
|
|
as arguments, separated by
|
|
spaces. "<code class="literal">%systemd_postun</code>"
|
|
expects no
|
|
arguments. "<code class="literal">%systemd_postun_with_restart</code>"
|
|
expects the units to restart as
|
|
arguments.</p><p>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:</p><pre class="programlisting">%triggerun -- foobar < 0.47.11-1
|
|
if /sbin/chkconfig --level 5 foobar ; then
|
|
/bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || :
|
|
fi</pre><p>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
|
|
<span class="command"><strong>chkconfig</strong></span> 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.</p></div></div><div class="refsect1"><a name="idm274684279152"></a><h2 id="Porting Existing Daemons">Porting Existing Daemons<a class="headerlink" title="Permalink to this headline" href="#Porting%20Existing%20Daemons">¶</a></h2><p>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.</p><p>To port an existing SysV compatible daemon, the
|
|
following steps are recommended:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>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.</p></li><li class="listitem"><p>If the daemon offers
|
|
interfaces to other software running on the
|
|
local system via local <code class="constant">AF_UNIX</code> 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
|
|
<a href="sd_listen_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_listen_fds</span>(3)</span></a>
|
|
is checked for already passed sockets
|
|
first. If sockets are passed (i.e. when
|
|
<code class="function">sd_listen_fds()</code> returns a
|
|
positive value), skip the socket creation step
|
|
and use the passed sockets. Secondly, ensure
|
|
that the file system socket nodes for local
|
|
<code class="constant">AF_UNIX</code> 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.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>If the daemon exposes
|
|
interfaces via D-Bus, write and install a
|
|
D-Bus activation file for the service, see
|
|
above for details.</p></li></ol></div></div><div class="refsect1"><a name="idm274684268656"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
|
|
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
|
|
<a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>,
|
|
<a href="sd_listen_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_listen_fds</span>(3)</span></a>,
|
|
<a href="sd_notify.html"><span class="citerefentry"><span class="refentrytitle">sd_notify</span>(3)</span></a>,
|
|
<a href="daemon.html"><span class="citerefentry"><span class="refentrytitle">daemon</span>(3)</span></a>,
|
|
<a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
|
|
</p></div></div></body></html>
|