+++ /dev/null
-<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- This file is part of systemd.
-
- Copyright 2010 Lennart Poettering
-
- systemd is free software; you can redistribute it and/or modify it
- 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
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
--->
-
-<refentry id="daemon">
-
- <refentryinfo>
- <title>daemon</title>
- <productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>daemon</refentrytitle>
- <manvolnum>7</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>daemon</refname>
- <refpurpose>Writing and packaging system daemons</refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>Description</title>
-
- <para>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
- <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>
-
- <para>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.</para>
-
- <orderedlist>
- <listitem><para>Close all open file descriptors except
- standard input, output, and error (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
- <filename>/proc/self/fd</filename>, with a fallback of
- iterating from file descriptor 3 to the value returned by
- <function>getrlimit()</function> for
- <constant>RLIMIT_NOFILE</constant>. </para></listitem>
-
- <listitem><para>Reset all signal handlers to their default.
- This is best done by iterating through the available signals
- up to the limit of <constant>_NSIG</constant> and resetting
- them to <constant>SIG_DFL</constant>.</para></listitem>
-
- <listitem><para>Reset the signal mask
- using
- <function>sigprocmask()</function>.</para></listitem>
-
- <listitem><para>Sanitize the environment block, removing or
- resetting environment variables that might negatively impact
- daemon runtime.</para></listitem>
-
- <listitem><para>Call <function>fork()</function>, to create a
- background process.</para></listitem>
-
- <listitem><para>In the child, call
- <function>setsid()</function> to detach from any terminal and
- create an independent session.</para></listitem>
-
- <listitem><para>In the child, call <function>fork()</function>
- again, to 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
- re-parented to init/PID 1, as all daemons should
- be.</para></listitem>
-
- <listitem><para>In the daemon process, connect
- <filename>/dev/null</filename> to standard input, output, and
- error.</para></listitem>
-
- <listitem><para>In the daemon process, reset the umask to 0,
- so that the file modes passed to <function>open()</function>,
- <function>mkdir()</function> and suchlike directly control the
- access mode of the created files and
- directories.</para></listitem>
-
- <listitem><para>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.</para></listitem>
-
- <listitem><para>In the daemon process, write the daemon PID
- (as returned by <function>getpid()</function>) to a PID file,
- for example <filename>/run/foobar.pid</filename> (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.</para></listitem>
-
- <listitem><para>In the daemon process, drop privileges, if
- possible and applicable.</para></listitem>
-
- <listitem><para>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
- <function>fork()</function> and hence available in both the
- original and the daemon process.</para></listitem>
-
- <listitem><para>Call <function>exit()</function> in the
- original process. The process that invoked the daemon must be
- able to rely on that this <function>exit()</function> happens
- after initialization is complete and all external
- communication channels are established and
- accessible.</para></listitem>
- </orderedlist>
-
- <para>The BSD <function>daemon()</function> function should not
- be used, as it implements only a subset of these steps.</para>
-
- <para>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.</para>
- </refsect2>
-
- <refsect2>
- <title>New-Style Daemons</title>
-
- <para>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.</para>
-
- <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
- execute them when run as new-style service.</para>
-
- <para>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, with standard input/output/error connected to
- <filename>/dev/null</filename> unless otherwise configured. The
- umask is reset.
- </para>
-
- <para>It is recommended for new-style daemons to implement the
- following:</para>
-
- <orderedlist>
- <listitem><para>If <constant>SIGTERM</constant> is received,
- shut down the daemon and exit cleanly.</para></listitem>
-
- <listitem><para>If <constant>SIGHUP</constant> is received,
- reload the configuration files, if this
- applies.</para></listitem>
-
- <listitem><para>Provide a correct exit code from the main
- daemon process, as this is used by the init system to detect
- service errors and problems. It is recommended to follow the
- exit code scheme as defined in the <ulink
- url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
- recommendations for SysV init
- scripts</ulink>.</para></listitem>
-
- <listitem><para>If possible and applicable, expose the
- daemon's control interface via the D-Bus IPC system and grab a
- bus name as last step of initialization.</para></listitem>
-
- <listitem><para>For integration in systemd, provide a
- <filename>.service</filename> unit file that carries
- information about starting, stopping and otherwise maintaining
- the daemon. See
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details.</para></listitem>
-
- <listitem><para>As much as possible, rely on the init system's
- functionality to limit the access of the daemon to files,
- services and other resources, i.e. in the case of systemd,
- rely on systemd's resource limit control instead of
- implementing your own, rely on systemd's privilege dropping
- code instead of implementing it in the daemon, and similar.
- See
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for the available controls.</para></listitem>
-
- <listitem><para>If D-Bus is used, make your daemon
- bus-activatable 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.</para></listitem>
-
- <listitem><para>If your daemon provides services to other
- local processes or remote clients via a socket, it should be
- made socket-activatable following the scheme pointed out
- below. Like D-Bus activation, this enables on-demand starting
- of services as well as it allows improved parallelization of
- service start-up. Also, for state-less protocols (such as
- syslog, DNS), a daemon implementing socket-based activation
- can be restarted without losing a single request. See below
- for details.</para></listitem>
-
- <listitem><para>If applicable, a daemon should notify the init
- system about startup completion or status updates via the
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- interface.</para></listitem>
-
- <listitem><para>Instead of using the
- <function>syslog()</function> call to log directly to the
- system syslog service, a new-style daemon may choose to simply
- log to standard error via <function>fprintf()</function>,
- which is then forwarded to syslog by the init system. If log
- levels are necessary, these can be encoded by prefixing
- individual log lines with strings like
- <literal><4></literal> (for log level 4 "WARNING" in the
- syslog priority scheme), following a similar style as the
- Linux kernel's <function>printk()</function> level system. For
- details, see
- <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- and
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
-
- </orderedlist>
-
- <para>These recommendations are similar but not identical to the
- <ulink
- url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple
- MacOS X Daemon Requirements</ulink>.</para>
- </refsect2>
-
- </refsect1>
- <refsect1>
- <title>Activation</title>
-
- <para>New-style init systems provide multiple additional
- mechanisms to activate services, as detailed below. It is common
- that services are configured to be activated via more than one
- mechanism at the same time. An example for systemd:
- <filename>bluetoothd.service</filename> might get activated either
- when Bluetooth hardware is plugged in, or when an application
- accesses its programming interfaces via D-Bus. Or, a print server
- daemon might get activated when traffic arrives at an IPP port, or
- when a printer is plugged in, or when a file is queued in the
- printer spool directory. Even for services that are intended to be
- started on system bootup unconditionally, it is a good idea to
- implement some of the various activation schemes outlined below,
- in order to maximize parallelization. If a daemon implements a
- D-Bus service or listening socket, implementing the full bus and
- socket activation scheme allows starting of the daemon with its
- clients in parallel (which speeds up boot-up), since all its
- communication channels are established already, and no request is
- lost because client requests will be queued by the bus system (in
- case of D-Bus) or the kernel (in case of sockets) until the
- activation is completed.</para>
-
- <refsect2>
- <title>Activation on Boot</title>
-
- <para>Old-style daemons are usually activated exclusively on
- boot (and manually by the administrator) via SysV init scripts,
- as detailed in the <ulink
- url="http://refspecs.linuxbase.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 that 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
- <constant>IP_FREEBIND</constant> socket option, as accessible
- via <varname>FreeBind=yes</varname> in systemd socket files (see
- <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details). This option, when enabled, allows sockets to be
- bound to a non-local, not configured IP address, and hence
- allows bindings to a particular IP address before it actually
- becomes available, making such an explicit dependency to the
- configured address redundant. Another often suggested trigger
- for service activation is low system load. However, here too, a
- more convincing approach might be to make proper use of features
- of the operating system, in particular, the CPU or IO scheduler
- of Linux. Instead of scheduling jobs from userspace based on
- monitoring the OS scheduler, it is advisable to leave the
- scheduling of processes to the OS scheduler itself. systemd
- provides fine-grained access to the CPU and IO schedulers. If a
- process executed by the init system shall not negatively impact
- the amount of CPU or IO bandwidth available to other processes,
- it should be configured with
- <varname>CPUSchedulingPolicy=idle</varname> and/or
- <varname>IOSchedulingClass=idle</varname>. Optionally, this may
- be combined with timer-based activation to schedule background
- jobs during runtime and with minimal impact on the system, and
- remove it from the boot phase itself.</para>
- </refsect2>
-
- </refsect1>
- <refsect1>
- <title>Integration with Systemd</title>
-
- <refsect2>
- <title>Writing Systemd Unit Files</title>
-
- <para>When writing systemd unit files, it is recommended to
- consider the following suggestions:</para>
-
- <orderedlist>
- <listitem><para>If possible, do not use the
- <varname>Type=forking</varname> setting in service files. But
- if you do, make sure to set the PID file path using
- <varname>PIDFile=</varname>. See
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details.</para></listitem>
-
- <listitem><para>If your daemon registers a D-Bus name on the
- bus, make sure to use <varname>Type=dbus</varname> in the
- service file if possible.</para></listitem>
-
- <listitem><para>Make sure to set a good human-readable
- description string with
- <varname>Description=</varname>.</para></listitem>
-
- <listitem><para>Do not disable
- <varname>DefaultDependencies=</varname>, unless you really
- know what you do and your unit is involved in early boot or
- late system shutdown.</para></listitem>
-
- <listitem><para>Normally, little if any dependencies should
- need to be defined explicitly. However, if you do configure
- explicit dependencies, only refer to unit names listed on
- <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- or names introduced by your own package to keep the unit file
- operating system-independent.</para></listitem>
-
- <listitem><para>Make sure to include an
- <literal>[Install]</literal> section including installation
- information for the unit file. See
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details. To activate your service on boot, make sure to
- add a <varname>WantedBy=multi-user.target</varname> or
- <varname>WantedBy=graphical.target</varname> directive. To
- activate your socket on boot, make sure to add
- <varname>WantedBy=sockets.target</varname>. Usually, you also
- want to make sure that when your service is installed, your
- socket is installed too, hence add
- <varname>Also=foo.socket</varname> in your service file
- <filename>foo.service</filename>, for a hypothetical program
- <filename>foo</filename>.</para></listitem>
-
- </orderedlist>
- </refsect2>
-
- <refsect2>
- <title>Installing Systemd Service Files</title>
-
- <para>At the build installation time (e.g. <command>make
- install</command> during package build), packages are
- recommended to install their systemd unit files in the directory
- returned by <command>pkg-config systemd
- --variable=systemdsystemunitdir</command> (for system services)
- or <command>pkg-config systemd
- --variable=systemduserunitdir</command> (for user services).
- This will make the services available in the system on explicit
- request but not activate them automatically during boot.
- Optionally, during package installation (e.g. <command>rpm
- -i</command> by the administrator), symlinks should be created
- in the systemd configuration directories via the
- <command>enable</command> command of the
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- tool to activate them automatically on boot.</para>
-
- <para>Packages using
- <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- are recommended to use a configure script
- excerpt like the following to determine the
- unit installation path during source
- configuration:</para>
-
- <programlisting>PKG_PROG_PKG_CONFIG
-AC_ARG_WITH([systemdsystemunitdir],
- [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],,
- [with_systemdsystemunitdir=auto])
-AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [
- def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)
-
- AS_IF([test "x$def_systemdsystemunitdir" = "x"],
- [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"],
- [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])])
- with_systemdsystemunitdir=no],
- [with_systemdsystemunitdir="$def_systemdsystemunitdir"])])
-AS_IF([test "x$with_systemdsystemunitdir" != "xno"],
- [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])])
-AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</programlisting>
-
- <para>This snippet allows automatic
- installation of the unit files on systemd
- machines, and optionally allows their
- installation even on machines lacking
- systemd. (Modification of this snippet for the
- user unit directory is left as an exercise for the
- reader.)</para>
-
- <para>Additionally, to ensure that
- <command>make distcheck</command> continues to
- work, it is recommended to add the following
- to the top-level <filename>Makefile.am</filename>
- file in
- <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
- projects:</para>
-
- <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
- --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>
-
- <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
-
- <programlisting>if HAVE_SYSTEMD
-systemdsystemunit_DATA = \
- foobar.socket \
- foobar.service
-endif</programlisting>
-
- <para>In the
- <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- <filename>.spec</filename> file, use snippets like the following
- to enable/disable the service during
- installation/deinstallation. This makes use of the RPM macros
- shipped along systemd. Consult the packaging guidelines of your
- distribution for details and the equivalent for other package
- managers.</para>
-
- <para>At the top of the file:</para>
-
- <programlisting>BuildRequires: systemd
-%{?systemd_requires}</programlisting>
-
- <para>And as scriptlets, further down:</para>
-
- <programlisting>%post
-%systemd_post foobar.service foobar.socket
-
-%preun
-%systemd_preun foobar.service foobar.socket
-
-%postun
-%systemd_postun</programlisting>
-
- <para>If the service shall be restarted during upgrades, replace
- the <literal>%postun</literal> scriptlet above with the
- following:</para>
-
- <programlisting>%postun
-%systemd_postun_with_restart foobar.service</programlisting>
-
- <para>Note that <literal>%systemd_post</literal> and
- <literal>%systemd_preun</literal> expect the names of all units
- that are installed/removed as arguments, separated by spaces.
- <literal>%systemd_postun</literal> expects no arguments.
- <literal>%systemd_postun_with_restart</literal> expects the
- units to restart as arguments.</para>
-
- <para>To facilitate upgrades from a package version that shipped
- only SysV init scripts to a package version that ships both a
- SysV init script and a native systemd service file, use a
- fragment like the following:</para>
-
- <programlisting>%triggerun -- foobar < 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>Placing Daemon Data</title>
-
- <para>It is recommended to follow the general guidelines for
- placing package files, as discussed in
- <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
- </refsect1>
-
- <refsect1>
- <title>See Also</title>
- <para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- </para>
- </refsect1>
-
-</refentry>
~ianmdlvl / elogind.git / blobdiff