Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
+ Lesser General Public License for more details.
- You should have received a copy of the GNU General Public License
+ You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refnamediv>
<refname>daemon</refname>
- <refpurpose>Writing and Packaging System Daemons</refpurpose>
+ <refpurpose>Writing and packaging system daemons</refpurpose>
</refnamediv>
<refsect1>
descriptors 0, 1, 2). This ensures
that no accidentally passed file
descriptor stays around in the daemon
- process. On Linux this is best
+ process. On Linux, this is best
implemented by iterating through
<filename>/proc/self/fd</filename>,
with a fallback of iterating from file
best done by iterating through the
available signals up to the limit of
_NSIG and resetting them to
- SIG_DFL.</para></listitem>
+ <constant>SIG_DFL</constant>.</para></listitem>
<listitem><para>Reset the signal mask
using
<listitem><para>In the child, call
<function>fork()</function> again, to
- ensure the daemon can never re-aquire
+ ensure that the daemon can never re-acquire
a terminal again.</para></listitem>
<listitem><para>Call <function>exit()</function> in the
first child, so that only the second
child (the actual daemon process)
stays around. This ensures that the
- daemon process is reparented to
+ daemon process is re-parented to
init/PID 1, as all daemons should
be.</para></listitem>
<function>getpid()</function>) to a
PID file, for example
<filename>/var/run/foobar.pid</filename>
- (for a hypothetical daemon "foobar"),
+ (for a hypothetical daemon "foobar")
to ensure that the daemon cannot be
started more than once. This must be
implemented in race-free fashion so
that the PID file is only updated when
- at the same time it is verified that
+ 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
+ foreign process. Commonly, some kind of
file locking is employed to implement
this logic.</para></listitem>
applicable.</para></listitem>
<listitem><para>From the daemon
- process notify the original process
+ process, notify the original process
started that initialization is
complete. This can be implemented via
an unnamed pipe or similar
<function>exit()</function> in the
original process. The process that
invoked the daemon must be able to
- rely that this
+ rely on that this
<function>exit()</function> happens
after initialization is complete and
all external communication channels
- established and
+ are established and
accessible.</para></listitem>
</orderedlist>
compatibility with SysV systems should
implement the scheme pointed out
above. However, it is recommended to make this
- behaviour optional and configurable via a
- command line argument, to ease debugging as
+ behavior optional and configurable via a
+ command line argument to ease debugging as
well as to simplify integration into systems
using systemd.</para>
</refsect2>
runtime and simplifies their
implementation.</para>
- <para>For developing a new-style daemon none
+ <para>For developing a new-style daemon, none
of the initialization steps recommended for
SysV daemons need to be implemented. New-style
init systems such as systemd make all of them
redundant. Moreover, since some of these steps
interfere with process monitoring, file
descriptor passing and other functionality of
- the init system it is recommended not to
+ the init system, it is recommended not to
execute them when run as new-style
service.</para>
<para>Note that new-style init systems
guarantee execution of daemon processes in
- clean process contexts: it is guaranteed that
+ 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
to implement the following:</para>
<orderedlist>
- <listitem><para>If SIGTERM is
+ <listitem><para>If <constant>SIGTERM</constant> is
received, shut down the daemon and
exit cleanly.</para></listitem>
- <listitem><para>If SIGHUP is received,
+ <listitem><para>If <constant>SIGHUP</constant> is received,
reload the configuration files, if
this applies.</para></listitem>
scripts</ulink>.</para></listitem>
<listitem><para>If possible and
- applicable expose the daemon's control
+ applicable, expose the daemon's control
interface via the D-Bus IPC system and
grab a bus name as last step of
initialization.</para></listitem>
for details.</para></listitem>
<listitem><para>As much as possible,
- rely on the init systemd's
+ 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
+ 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
controls.</para></listitem>
<listitem><para>If D-Bus is used, make
- your daemon bus-activatable, via
+ your daemon bus-activatable by
supplying a D-Bus service activation
configuration file. This has multiple
advantages: your daemon may be started
parallel to other daemons requiring it
-- which maximizes parallelization and
boot-up speed; your daemon can be
- restarted on failure, without losing
+ restarted on failure without losing
any bus requests, as the bus queues
requests for activatable services. See
below for details.</para></listitem>
socket, it should be made
socket-activatable following the
scheme pointed out below. Like D-Bus
- activation this enables on-demand
+ 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
+ protocols (such as syslog, DNS), a
daemon implementing socket-based
activation can be restarted without
losing a single request. See below for
details.</para></listitem>
- <listitem><para>If applicable a daemon
+ <listitem><para>If applicable, a daemon
should notify the init system about
startup completion or status updates
via the
<listitem><para>Instead of using the
<function>syslog()</function> call to log directly to the
- system logger, a new-style daemon may
+ system syslog service, a new-style daemon may
choose to simply log to STDERR via
<function>fprintf()</function>, which is then forwarded to
syslog by the init system. If log
- priorities are necessary these can be
+ priorities are necessary, these can be
encoded by prefixing individual log
lines with strings like "<4>"
(for log priority 4 "WARNING" in the
kind of logging may be enabled by
setting
<varname>StandardError=syslog</varname>
- in the service unit file. For details
+ in the service unit file. For details,
see
- <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
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
+ unconditionally, it is a good idea to implement some of
the various activation schemes outlined below, in
- order to maximize parallelization: if a daemon
+ 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
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
+ case of sockets) until the activation is
completed.</para>
<refsect2>
url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
Linux Standard Base Core
Specification</ulink>. This method of
- activation is supported ubiquitiously on Linux
+ activation is supported ubiquitously on Linux
init systems, both old-style and new-style
- systems. Among other issues SysV init scripts
+ 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
<para>In systemd, if the developer or
administrator wants to make sure a service or
- other unit is activated automatically on boot
+ other unit is activated automatically on boot,
it is recommended to place a symlink to the
unit file in the <filename>.wants/</filename>
directory of either
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
+ 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
+ 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
+ Optionally, activation of the service can be
delayed until the first inbound traffic
- arrives at the socket, to implement on-demand
+ 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
+ are established. In addition to that, daemons
can be restarted with losing only a minimal
- number of client transactions or even any
+ 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
<para>New-style daemons which support socket
activation must be able to receive their
- sockets from the init system, instead of of
+ 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
+ this scheme provided by systemd, see
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and
- <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. For
details about porting existing daemons to
- socket-based activation see below. With
- minimal effort it is possible to implement
+ socket-based activation, 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
units, which are described in
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. When
configuring socket units for socket-based
- activation it is essential that all listening
+ activation, it is essential that all listening
sockets are pulled in by the special target
unit <filename>sockets.target</filename>. It
is recommended to place a
<varname>WantedBy=sockets.target</varname>
directive in the <literal>[Install]</literal>
- section, to automatically add such a
+ section to automatically add such a
dependency on installation of a socket
unit. Unless
<varname>DefaultDependencies=no</varname> is
- set the necessary ordering dependencies are
+ set, the necessary ordering dependencies are
implicitly created for all socket units. For
more information about
- <filename>sockets.target</filename> see
+ <filename>sockets.target</filename>, see
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. It
is not necessary or recommended to place any
additional dependencies on socket units (for
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
+ daemon, use the
<varname>SystemdService=</varname> directive
- in these service files, to configure the
+ 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
+ service. e.g.: For a D-Bus service whose D-Bus
activation file is named
<filename>org.freedesktop.RealtimeKit.service</filename>,
make sure to set
<varname>SystemdService=rtkit-daemon.service</varname>
- in that file, to bind it to the systemd
+ in that file to bind it to the systemd
service
<filename>rtkit-daemon.service</filename>. This
is needed to make sure that the daemon is
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
+ new-style init system, it is possible to bind
activation to hardware plug/unplug events. In
systemd, kernel devices appearing in the
sysfs/udev device tree can be exposed as units
if they are tagged with the string
- "<literal>systemd</literal>". Like any other
- kind of unit they may then pull in other units
- when activated (i.e. Plugged in) and thus
- implement device-based activation. Systemd
+ <literal>systemd</literal>. Like any other
+ kind of unit, they may then pull in other units
+ when activated (i.e. plugged in) and thus
+ implement device-based activation. systemd
dependencies may be encoded in the udev
database via the
<varname>SYSTEMD_WANTS=</varname>
property. See
<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details. Often it is nicer to pull in
+ for details. Often, it is nicer to pull in
services from devices only indirectly via
- dedicated targets. Example: instead of pulling
+ dedicated targets. Example: Instead of pulling
in <filename>bluetoothd.service</filename>
from all the various bluetooth dongles and
other hardware available, pull in
<para>Other forms of activation have been
suggested and implemented in some
- systems. However, often there are simpler or
+ 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
+ above. Example: Sometimes, it appears useful to
start daemons or <filename>.socket</filename>
units when a specific IP address is configured
on a network interface, because network
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
+ 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
to the CPU and IO schedulers. If a process
executed by the init system shall not
negatively impact the amount of CPU or IO
- bandwith available to other processes, it
+ bandwidth available to other processes, it
should be configured with
<varname>CPUSchedulingPolicy=idle</varname>
and/or
suggestions:</para>
<orderedlist>
- <listitem><para>If possible do not use
+ <listitem><para>If possible, do not use
the <varname>Type=forking</varname>
setting in service files. But if you
do, make sure to set the PID file path
operating
system-independent.</para></listitem>
- <listitem><para>Since not all syslog
- implementations are socket-activatable
- yet, it is recommended to place an
- <varname>After=syslog.target</varname>
- dependency in service files for
- daemons that can log to
- syslog. <filename>syslog.target</filename>
- then either pulls in the syslog daemon
- itself or simply the activation
- socket. A <varname>Wants=</varname> or
- even <varname>Requires=</varname>
- dependency should generally not be
- added, since it should be up to the
- administrator whether he wants to
- enable logging or not, and most syslog
- clients work fine if no log daemon is
- running.</para></listitem>
-
<listitem><para>Make sure to include
an <literal>[Install]</literal>
section including installation
information for the unit file. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. To activate your service
- on boot make sure to add a
+ on boot, make sure to add a
<varname>WantedBy=multi-user.target</varname>
or
<varname>WantedBy=graphical.target</varname>
directive. To activate your socket on
boot, make sure to add
- <varname>WantedBy=sockets.target</varname>. Usually
+ <varname>WantedBy=sockets.target</varname>. Usually,
you also want to make sure that when
- your service is installed your socket
+ your service is installed, your socket
is installed too, hence add
<varname>Also=foo.socket</varname> in
your service file
<para>At the build installation time
(e.g. <command>make install</command> during
- package build) packages are recommended to
+ package build), packages are recommended to
install their systemd unit files in the
directory returned by <command>pkg-config
systemd
--variable=systemdsystemunitdir</command> (for
- system services), resp. <command>pkg-config
+ system services) or <command>pkg-config
systemd
- --variable=systemdsessionunitdir</command>
- (for session services). This will make the
+ --variable=systemduserunitdir</command>
+ (for user services). This will make the
services available in the system on explicit
request but not activate them automatically
during boot. Optionally, during package
installation (e.g. <command>rpm -i</command>
- by the administrator) symlinks should be
+ by the administrator), symlinks should be
created in the systemd configuration
directories via the <command>enable</command>
command of the
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- tool, to activate them automatically on
+ tool to activate them automatically on
boot.</para>
<para>Packages using
AC_ARG_WITH([systemdsystemunitdir],
AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
[], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
-AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
-AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir"])</programlisting>
+if test "x$with_systemdsystemunitdir" != xno; then
+ AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
+fi
+AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ])</programlisting>
<para>This snippet allows automatic
installation of the unit files on systemd
machines, and optionally allows their
installation even on machines lacking
systemd. (Modification of this snippet for the
- session unit directory is left as excercise to the
+ user unit directory is left as an exercise for the
reader.)</para>
<para>Additionally, to ensure that
<para>In the
<citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- <filename>.spec</filename> file use a snippet like
- the following to enable/disable the service
- during installation/deinstallation. Consult
+ <filename>.spec</filename> file, use snippets
+ like the following to enable/disable the
+ service during
+ installation/deinstallation. This makes use of
+ the RPM macros shipped along systemd. Consult
the packaging guidelines of your distribution
for details and the equivalent for other
- package managers:</para>
+ package managers.</para>
- <programlisting>%post
-if [ $1 -eq 1 ]; then
- # On install, enable (but don't start) the units by default
- /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&1 || :
+ <para>At the top of the file:</para>
- # Alternatively, just call /bin/systemctl daemon-reload here,
- # if the daemon should not be enabled by default on package
- # installation
-fi
+ <programlisting>BuildRequires: systemd
+%{?systemd_requires}</programlisting>
+
+ <para>And as scriptlets, further down:</para>
+
+ <programlisting>%post
+%systemd_post foobar.service foobar.socket
%preun
-if [ $1 -eq 0 ]; then
- # On uninstall, disable and stop the units
- /bin/systemctl disable foobar.service foobar.socket >/dev/null 2>&1 || :
- /bin/systemctl stop foobar.service foobar.socket >/dev/null 2>&1 || :
-fi
+%systemd_preun foobar.service foobar.socket
%postun
-# On upgrade and uninstall, reload init system configuration, to make systemd honour changed unit files
-/bin/systemctl daemon-reload >/dev/null 2>&1 || :
-if [ $1 -ge 1 ] ; then
- # Optionally, on upgrade, restart the daemon
- /bin/systemctl try-restart foobar.service >/dev/null 2>&1 || :
-fi</programlisting>
-
- <para>Depending on whether your service should
- or should not be started/stopped/restarted
- during package installation, deinstallation or
- upgrade, a different set of commands may be
- specified. See
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- for details.</para>
+%systemd_postun</programlisting>
+
+ <para>If the service shall be restarted during
+ upgrades, replace the
+ <literal>%postun</literal> scriptlet above
+ with the following:</para>
+
+ <programlisting>%postun
+%systemd_postun_with_restart foobar.service</programlisting>
+
+ <para>Note that
+ <literal>%systemd_post</literal> and
+ <literal>%systemd_preun</literal> expect the
+ names of all units that are installed/removed
+ as arguments, separated by
+ spaces. <literal>%systemd_postun</literal>
+ expects no
+ arguments. <literal>%systemd_postun_with_restart</literal>
+ expects the units to restart as
+ arguments.</para>
<para>To facilitate upgrades from a package
version that shipped only SysV init scripts to
a fragment like the following:</para>
<programlisting>%triggerun -- foobar < 0.47.11-1
-if /sbin/chkconfig foobar ; then
- /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&1 || :
+if /sbin/chkconfig --level 5 foobar ; then
+ /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || :
fi</programlisting>
<para>Where 0.47.11-1 is the first package
version that includes the native unit
file. This fragment will ensure that the first
- time the unit file is installed it will be
+ 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
<title>Porting Existing Daemons</title>
<para>Since new-style init systems such as systemd are
- compatible with traditional SysV init systems it is
+ compatible with traditional SysV init systems, it is
not strictly necessary to port existing daemons to the
- new style. However doing so offers additional
+ new style. However, doing so offers additional
functionality to the daemons as well as simplifying
integration into new-style init systems.</para>
- <para>To port an existing SysV compatible daemon the
+ <para>To port an existing SysV compatible daemon, the
following steps are recommended:</para>
<orderedlist>
<listitem><para>If the daemon offers
interfaces to other software running on the
- local system via local AF_UNIX sockets,
+ local system via local <constant>AF_UNIX</constant> sockets,
consider implementing socket-based activation
- (see above). Usually a minimal patch is
+ (see above). Usually, a minimal patch is
sufficient to implement this: Extend the
socket creation in the daemon code so that
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<function>sd_listen_fds()</function> returns a
positive value), skip the socket creation step
and use the passed sockets. Secondly, ensure
- that the file-system socket nodes for local
- AF_UNIX sockets used in the socket-based
+ that the file system socket nodes for local
+ <constant>AF_UNIX</constant> sockets used in the socket-based
activation are not removed when the daemon
shuts down, if sockets have been
passed. Third, if the daemon normally closes
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
~ianmdlvl / elogind.git / blobdiff