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>
in SysV Unix. Modern daemons should follow a simpler
yet more powerful scheme (here called "new-style"
daemons), as implemented by
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
+ manual page covers both schemes, and in
+ particular includes recommendations for daemons that
+ shall be included in the systemd init system.</para>
<refsect2>
<title>SysV Daemons</title>
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>
recommendations for SysV init
scripts</ulink>.</para></listitem>
- <listitem><para>As much as possible,
- rely on systemd's functionality to
- limit the access of the daemon to
- files, services and other
- resources. i.e. rely on systemd's
- resource limit control instead of
- implementing your own, rely on
- systemd's privilege dropping code
- instead of implementing it in the
- daemon, and similar. See
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for the available
- controls.</para></listitem>
-
<listitem><para>If 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>
+ <listitem><para>For integration in
+ systemd, provide a
+ <filename>.service</filename> unit
+ file that carries information about
+ starting, stopping and otherwise
+ maintaining the daemon. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para></listitem>
+
+ <listitem><para>As much as possible,
+ rely on the init system's
+ functionality to limit the access of
+ the daemon to files, services and
+ other resources, i.e. in the case of
+ systemd, rely on systemd's resource
+ limit control instead of implementing
+ your own, rely on systemd's privilege
+ dropping code instead of implementing
+ it in the daemon, and similar. See
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for the available
+ controls.</para></listitem>
+
<listitem><para>If D-Bus is used, make
- your daemon bus-activatable, via
+ 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>
MacOS X Daemon Requirements</ulink>.</para>
</refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Activation</title>
+
+ <para>New-style init systems provide multiple
+ additional mechanisms to activate services, as
+ detailed below. It is common that services are
+ configured to be activated via more than one mechanism
+ at the same time. An example for systemd:
+ <filename>bluetoothd.service</filename> might get
+ activated either when Bluetooth hardware is plugged
+ in, or when an application accesses its programming
+ interfaces via D-Bus. Or, a print server daemon might
+ get activated when traffic arrives at an IPP port, or
+ when a printer is plugged in, or when a file is queued
+ in the printer spool directory. Even for services that
+ are intended to be started on system bootup
+ unconditionally, it is a good idea to implement some of
+ the various activation schemes outlined below, in
+ order to maximize parallelization. If a daemon
+ implements a D-Bus service or listening socket,
+ implementing the full bus and socket activation scheme
+ allows starting of the daemon with its clients in
+ parallel (which speeds up boot-up), since all its
+ communication channels are established already, and no
+ request is lost because client requests will be queued
+ by the bus system (in case of D-Bus) or the kernel (in
+ case of sockets) until the activation is
+ completed.</para>
+
+ <refsect2>
+ <title>Activation on Boot</title>
+
+ <para>Old-style daemons are usually activated
+ exclusively on boot (and manually by the
+ administrator) via SysV init scripts, as
+ detailed in the <ulink
+ url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
+ Linux Standard Base Core
+ Specification</ulink>. This method of
+ activation is supported ubiquitously on Linux
+ init systems, both old-style and new-style
+ systems. Among other issues, SysV init scripts
+ have the disadvantage of involving shell
+ scripts in the boot process. New-style init
+ systems generally employ updated versions of
+ activation, both during boot-up and during
+ runtime and using more minimal service
+ description files.</para>
+
+ <para>In systemd, if the developer or
+ administrator wants to make sure a service or
+ other unit is activated automatically on boot,
+ it is recommended to place a symlink to the
+ unit file in the <filename>.wants/</filename>
+ directory of either
+ <filename>multi-user.target</filename> or
+ <filename>graphical.target</filename>, which
+ are normally used as boot targets at system
+ startup. See
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details about the
+ <filename>.wants/</filename> directories, and
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details about the two boot targets.</para>
+
+ </refsect2>
+
<refsect2>
<title>Socket-Based Activation</title>
+
+ <para>In order to maximize the possible
+ parallelization and robustness and simplify
+ configuration and development, it is
+ recommended for all new-style daemons that
+ communicate via listening sockets to employ
+ socket-based activation. In a socket-based
+ activation scheme, the creation and binding of
+ the listening socket as primary communication
+ channel of daemons to local (and sometimes
+ remote) clients is moved out of the daemon
+ code and into the init system. Based on
+ per-daemon configuration, the init system
+ installs the sockets and then hands them off
+ to the spawned process as soon as the
+ respective daemon is to be started.
+ Optionally, activation of the service can be
+ delayed until the first inbound traffic
+ arrives at the socket to implement on-demand
+ activation of daemons. However, the primary
+ advantage of this scheme is that all providers
+ and all consumers of the sockets can be
+ started in parallel as soon as all sockets
+ are established. In addition to that, daemons
+ can be restarted with losing only a minimal
+ number of client transactions, or even any
+ client request at all (the latter is
+ particularly true for state-less protocols,
+ such as DNS or syslog), because the socket
+ stays bound and accessible during the restart,
+ and all requests are queued while the daemon
+ cannot process them.</para>
+
+ <para>New-style daemons which support socket
+ activation must be able to receive their
+ sockets from the init system instead of
+ creating and binding them themselves. For
+ details about the programming interfaces for
+ this scheme provided by systemd, see
+ <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. For
+ details about porting existing daemons to
+ socket-based activation, see below. With
+ minimal effort, it is possible to implement
+ socket-based activation in addition to
+ traditional internal socket creation in the
+ same codebase in order to support both
+ new-style and old-style init systems from the
+ same daemon binary.</para>
+
+ <para>systemd implements socket-based
+ activation via <filename>.socket</filename>
+ units, which are described in
+ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. When
+ configuring socket units for socket-based
+ activation, it is essential that all listening
+ sockets are pulled in by the special target
+ unit <filename>sockets.target</filename>. It
+ is recommended to place a
+ <varname>WantedBy=sockets.target</varname>
+ directive in the <literal>[Install]</literal>
+ section to automatically add such a
+ dependency on installation of a socket
+ unit. Unless
+ <varname>DefaultDependencies=no</varname> is
+ set, the necessary ordering dependencies are
+ implicitly created for all socket units. For
+ more information about
+ <filename>sockets.target</filename>, see
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. It
+ is not necessary or recommended to place any
+ additional dependencies on socket units (for
+ example from
+ <filename>multi-user.target</filename> or
+ suchlike) when one is installed in
+ <filename>sockets.target</filename>.</para>
</refsect2>
<refsect2>
<title>Bus-Based Activation</title>
+
+ <para>When the D-Bus IPC system is used for
+ communication with clients, new-style daemons
+ should employ bus activation so that they are
+ automatically activated when a client
+ application accesses their IPC
+ interfaces. This is configured in D-Bus
+ service files (not to be confused with systemd
+ service unit files!). To ensure that D-Bus
+ uses systemd to start-up and maintain the
+ daemon, use the
+ <varname>SystemdService=</varname> directive
+ in these service files to configure the
+ matching systemd service for a D-Bus
+ service. e.g.: For a D-Bus service whose D-Bus
+ activation file is named
+ <filename>org.freedesktop.RealtimeKit.service</filename>,
+ make sure to set
+ <varname>SystemdService=rtkit-daemon.service</varname>
+ in that file to bind it to the systemd
+ service
+ <filename>rtkit-daemon.service</filename>. This
+ is needed to make sure that the daemon is
+ started in a race-free fashion when activated
+ via multiple mechanisms simultaneously.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Device-Based Activation</title>
+
+ <para>Often, daemons that manage a particular
+ type of hardware should be activated only when
+ the hardware of the respective kind is plugged
+ in or otherwise becomes available. In a
+ new-style init system, it is possible to bind
+ activation to hardware plug/unplug events. In
+ systemd, kernel devices appearing in the
+ sysfs/udev device tree can be exposed as units
+ if they are tagged with the string
+ <literal>systemd</literal>. Like any other
+ kind of unit, they may then pull in other units
+ when activated (i.e. plugged in) and thus
+ implement device-based activation. systemd
+ dependencies may be encoded in the udev
+ database via the
+ <varname>SYSTEMD_WANTS=</varname>
+ property. See
+ <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details. Often, it is nicer to pull in
+ services from devices only indirectly via
+ dedicated targets. Example: Instead of pulling
+ in <filename>bluetoothd.service</filename>
+ from all the various bluetooth dongles and
+ other hardware available, pull in
+ bluetooth.target from them and
+ <filename>bluetoothd.service</filename> from
+ that target. This provides for nicer
+ abstraction and gives administrators the
+ option to enable
+ <filename>bluetoothd.service</filename> via
+ controlling a
+ <filename>bluetooth.target.wants/</filename>
+ symlink uniformly with a command like
+ <command>enable</command> of
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ instead of manipulating the udev
+ ruleset.</para>
</refsect2>
<refsect2>
<title>Path-Based Activation</title>
+
+ <para>Often, runtime of daemons processing
+ spool files or directories (such as a printing
+ system) can be delayed until these file system
+ objects change state, or become
+ non-empty. New-style init systems provide a
+ way to bind service activation to file system
+ changes. systemd implements this scheme via
+ path-based activation configured in
+ <filename>.path</filename> units, as outlined
+ in
+ <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Timer-Based Activation</title>
+
+ <para>Some daemons that implement clean-up
+ jobs that are intended to be executed in
+ regular intervals benefit from timer-based
+ activation. In systemd, this is implemented
+ via <filename>.timer</filename> units, as
+ described in
+ <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</refsect2>
+ <refsect2>
+ <title>Other Forms of Activation</title>
+
+ <para>Other forms of activation have been
+ suggested and implemented in some
+ systems. However, there are often simpler or
+ better alternatives, or they can be put
+ together of combinations of the schemes
+ above. Example: Sometimes, it appears useful to
+ start daemons or <filename>.socket</filename>
+ units when a specific IP address is configured
+ on a network interface, because network
+ sockets shall be bound to the
+ address. However, an alternative to implement
+ this is by utilizing the Linux IP_FREEBIND
+ socket option, as accessible via
+ <varname>FreeBind=yes</varname> in systemd
+ socket files (see
+ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details). This option, when enabled,
+ allows sockets to be bound to a non-local, not
+ configured IP address, and hence allows
+ bindings to a particular IP address before it
+ actually becomes available, making such an
+ explicit dependency to the configured address
+ redundant. Another often suggested trigger for
+ service activation is low system
+ load. However, here too, a more convincing
+ approach might be to make proper use of
+ features of the operating system, in
+ particular, the CPU or IO scheduler of
+ Linux. Instead of scheduling jobs from
+ userspace based on monitoring the OS
+ scheduler, it is advisable to leave the
+ scheduling of processes to the OS scheduler
+ itself. systemd provides fine-grained access
+ to the CPU and IO schedulers. If a process
+ executed by the init system shall not
+ negatively impact the amount of CPU or IO
+ bandwidth available to other processes, it
+ should be configured with
+ <varname>CPUSchedulingPolicy=idle</varname>
+ and/or
+ <varname>IOSchedulingClass=idle</varname>. Optionally,
+ this may be combined with timer-based
+ activation to schedule background jobs during
+ runtime and with minimal impact on the system,
+ and remove it from the boot phase
+ itself.</para>
+ </refsect2>
+
+ </refsect1>
+ <refsect1>
+ <title>Integration with Systemd</title>
+
<refsect2>
<title>Writing Systemd Unit Files</title>
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
<listitem><para>If your daemon
registers a D-Bus name on the bus,
make sure to use
- <varname>Type=dbus</varname> if
+ <varname>Type=dbus</varname> in the
+ service file if
possible.</para></listitem>
<listitem><para>Make sure to set a
system-independent.</para></listitem>
<listitem><para>Make sure to include
- an <literal>[Install]</literal> section including
- installation information for the unit
- file. See
+ 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.</para></listitem>
+ <varname>WantedBy=graphical.target</varname>
+ directive. To activate your socket on
+ boot, make sure to add
+ <varname>WantedBy=sockets.target</varname>. Usually,
+ you also want to make sure that when
+ your service is installed, your socket
+ is installed too, hence add
+ <varname>Also=foo.socket</varname> in
+ your service file
+ <filename>foo.service</filename>, for
+ a hypothetical program
+ <filename>foo</filename>.</para></listitem>
</orderedlist>
</refsect2>
<refsect2>
- <title>Installing Service Files</title>
+ <title>Installing Systemd Service Files</title>
<para>At the build installation time
(e.g. <command>make install</command> during
- package build) packages are recommended to
+ package build), packages are recommended to
install their systemd unit files in the
directory returned by <command>pkg-config
systemd
- --variable=systemdsystemnunitdir</command>
- (for system services),
- resp. <command>pkg-config systemd
- --variable=systemdsessionunitdir</command>
- (for session services). This will make the
+ --variable=systemdsystemunitdir</command> (for
+ system services) or <command>pkg-config
+ systemd
+ --variable=systemduserunitdir</command>
+ (for user services). This will make the
services available in the system on explicit
request but not activate them automatically
during boot. Optionally, during package
installation (e.g. <command>rpm -i</command>
- by the administrator) symlinks should be
+ by the administrator), symlinks should be
created in the systemd configuration
- directories via the
- <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- tool, to activate them automatically on
+ directories via the <command>enable</command>
+ command of the
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ tool to activate them automatically on
boot.</para>
<para>Packages using
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
- packaging managers:</para>
+ package managers.</para>
- <programlisting>%post
-/usr/bin/systemd-install enable foobar.service foobar.socket >/dev/null 2>&1 || :
+ <para>At the top of the file:</para>
-%preun
-if [ "$1" -eq 0 ]; then
- /usr/bin/systemd-install disable foobar.service foobar.socket >/dev/null 2>&1 || :
-fi</programlisting>
+ <programlisting>BuildRequires: systemd
+%{?systemd_requires}</programlisting>
- </refsect2>
+ <para>And as scriptlets, further down:</para>
- <refsect2>
- <title>Porting Existing Daemons</title>
-
- <para>Since new-style init systems such as
- systemd are compatible with traditional SysV
- init systems it is not strictly necessary to
- port existing daemons to the new
- style. However doing this offers additional
- functionality to the daemons as well as it
- simplifies integration into new-style init
- systems.</para>
-
- <para>To port an existing SysV compatible
- daemon the following steps are
- recommended:</para>
-
- <orderedlist>
- <listitem><para>If not already
- implemented, add an optional command
- line switch to the daemon to disable
- daemonization. This is useful not only
- for using the daemon in new-style init
- systems, but also to ease debugging.</para></listitem>
-
- <listitem><para>If the daemon offers
- interfaces to other software running
- on the local system via local AF_UNIX
- sockets, consider implementing
- socket-based activation (see
- above). Usually a minimal patch is
- sufficient to implement this: Extend
- the socket creation in the daemon code
- so that
- <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- is checked for already passed sockets
- first. If sockets are passed
- (i.e. when
- <function>sd_listen_fds()</function>
- returns a positive value), skip the
- socket createn step and use the passed
- sockets. Secondly, ensure that the
- file-system socket nodes for local
- AF_UNIX sockets used in the
- socket-based activation are not
- removed when the daemon shuts down, if
- sockets have been passed. Third, if
- the daemon normally closes all
- remaining open file descriptors as
- part of its initialization, the
- sockets passed from the init system
- must be spared. Since new-style init
- systems guarantee that no left-over
- file descriptors are passed to
- executed processes, it might be a good
- choice to simply skip the closing of
- all remaining open file descriptors if
- file descriptors are
- passed.</para></listitem>
-
- <listitem><para>Write and install a
- systemd unit file for the service (and
- the sockets if socket-based activation
- is used, as well as a path unit file,
- if the daemon processes a spool
- directory), see above for
- details.</para></listitem>
+ <programlisting>%post
+%systemd_post foobar.service foobar.socket
- <listitem><para>If the daemon exposes
- interfaces via D-Bus, write and
- install a D-Bus activation file for
- the service, see above for
- details.</para></listitem>
- </orderedlist>
+%preun
+%systemd_preun foobar.service foobar.socket
+
+%postun
+%systemd_postun</programlisting>
+
+ <para>If the service shall be restarted during
+ upgrades, replace the
+ <literal>%postun</literal> scriptlet above
+ with the following:</para>
+
+ <programlisting>%postun
+%systemd_postun_with_restart foobar.service</programlisting>
+
+ <para>Note that
+ <literal>%systemd_post</literal> and
+ <literal>%systemd_preun</literal> expect the
+ names of all units that are installed/removed
+ as arguments, separated by
+ spaces. <literal>%systemd_postun</literal>
+ expects no
+ arguments. <literal>%systemd_postun_with_restart</literal>
+ expects the units to restart as
+ arguments.</para>
+
+ <para>To facilitate upgrades from a package
+ version that shipped only SysV init scripts to
+ a package version that ships both a SysV init
+ script and a native systemd service file, use
+ a fragment like the following:</para>
+
+ <programlisting>%triggerun -- foobar < 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</programlisting>
+ <para>Where 0.47.11-1 is the first package
+ version that includes the native unit
+ file. This fragment will ensure that the first
+ time the unit file is installed, it will be
+ enabled if and only if the SysV init script is
+ enabled, thus making sure that the enable
+ status is not changed. Note that
+ <command>chkconfig</command> is a command
+ specific to Fedora which can be used to check
+ whether a SysV init script is enabled. Other
+ operating systems will have to use different
+ commands here.</para>
</refsect2>
-
</refsect1>
+ <refsect1>
+ <title>Porting Existing Daemons</title>
+
+ <para>Since new-style init systems such as systemd are
+ compatible with traditional SysV init systems, it is
+ not strictly necessary to port existing daemons to the
+ new style. However, doing so offers additional
+ functionality to the daemons as well as simplifying
+ integration into new-style init systems.</para>
+
+ <para>To port an existing SysV compatible daemon, the
+ following steps are recommended:</para>
+
+ <orderedlist>
+ <listitem><para>If not already implemented,
+ add an optional command line switch to the
+ daemon to disable daemonization. This is
+ useful not only for using the daemon in
+ new-style init systems, but also to ease
+ debugging.</para></listitem>
+
+ <listitem><para>If the daemon offers
+ interfaces to other software running on the
+ local system via local <constant>AF_UNIX</constant> sockets,
+ consider implementing socket-based activation
+ (see above). Usually, a minimal patch is
+ sufficient to implement this: Extend the
+ socket creation in the daemon code so that
+ <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ is checked for already passed sockets
+ first. If sockets are passed (i.e. when
+ <function>sd_listen_fds()</function> returns a
+ positive value), skip the socket creation step
+ and use the passed sockets. Secondly, ensure
+ that the file system socket nodes for local
+ <constant>AF_UNIX</constant> sockets used in the socket-based
+ activation are not removed when the daemon
+ shuts down, if sockets have been
+ passed. Third, if the daemon normally closes
+ all remaining open file descriptors as part of
+ its initialization, the sockets passed from
+ the init system must be spared. Since
+ new-style init systems guarantee that no
+ left-over file descriptors are passed to
+ executed processes, it might be a good choice
+ to simply skip the closing of all remaining
+ open file descriptors if sockets are
+ passed.</para></listitem>
+
+ <listitem><para>Write and install a systemd
+ unit file for the service (and the sockets if
+ socket-based activation is used, as well as a
+ path unit file, if the daemon processes a
+ spool directory), see above for
+ details.</para></listitem>
+
+ <listitem><para>If the daemon exposes
+ interfaces via D-Bus, write and install a
+ D-Bus activation file for the service, see
+ above for details.</para></listitem>
+ </orderedlist>
+ </refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-install</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>
+ <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>