<?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">
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
<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 stdin, stdout,
- stderr (i.e. the first three file
- descriptors 0, 1, 2). This ensures
- that no accidentally passed file
- descriptor stays around in the daemon
- process. On Linux, this is best
- implemented by iterating through
- <filename>/proc/self/fd</filename>,
- with a fallback of iterating from file
- descriptor 3 to the value returned by
- <function>getrlimit()</function> for
- RLIMIT_NOFILE.</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
- _NSIG 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>/var/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. Commonly, some kind of
- file locking is employed to implement
- this logic.</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.freestandards.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
- priorities are necessary, these can be
- encoded by prefixing individual log
- lines with strings like "<4>"
- (for log priority 4 "WARNING" in the
- syslog priority scheme), following a
- similar style as the Linux kernel's
- <function>printk()</function> priority system. In fact,
- using this style of logging also
- enables the init system to optionally
- direct all application logging to the
- kernel log buffer (kmsg), as
- accessible via
- <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
- kind of logging may be enabled by
- setting
- <varname>StandardError=syslog</varname>
- in the service unit file. 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="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">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.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 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 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>
-
- <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><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
+ <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])
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" = "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>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><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
- projects:</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>
+ <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>
+ <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
-
<programlisting>if HAVE_SYSTEMD
+ <programlisting>if HAVE_SYSTEMD
systemdsystemunit_DATA = \
- foobar.socket \
- foobar.service
+ foobar.socket \
+ foobar.service
endif</programlisting>
- <para>In the
- <citerefentry><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>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>
+ <para>At the top of the file:</para>
-
<programlisting>BuildRequires: systemd
+ <programlisting>BuildRequires: systemd
%{?systemd_requires}</programlisting>
-
<para>And as scriptlets, further down:</para>
+ <para>And as scriptlets, further down:</para>
+ <programlisting>%post
%systemd_post foobar.service foobar.socket
%preun
%postun
%systemd_postun</programlisting>
- <para>If the service shall be restarted during
- upgrades, replace the
- <literal>%postun</literal> scriptlet above
- with the following:</para>
+ <para>If the service shall be restarted during upgrades, replace
+ the <literal>%postun</literal> scriptlet above with the
+ following:</para>
-
<programlisting>%postun
+ <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
+ <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 || :
+ /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>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>
- </para>
- </refsect1>
+ <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