summaryrefslogtreecommitdiff
path: root/man/daemon.xml
diff options
context:
space:
mode:
authorAnthony G. Basile <blueness@gentoo.org>2012-11-15 10:33:16 -0500
committerAnthony G. Basile <blueness@gentoo.org>2012-11-15 10:33:16 -0500
commit7d4a62f8c1404ed426500b97af03d4ef8d034a71 (patch)
tree2436cd4f0460a3a3d589875d4ffba55556f3c582 /man/daemon.xml
parent2944f347d087ff24ec808e4b70fe104a772a97a0 (diff)
Isolation of udev code from remaining systemd
This commit is a first attempt to isolate the udev code from the remaining code base. It intentionally does not modify any files but purely delete files which, on a first examination, appear to not be needed. This is a sweeping commit which may easily have missed needed code. Files can be retrieved by doing a checkout from the previous commit: git checkout 2944f347d0 -- <filename>
Diffstat (limited to 'man/daemon.xml')
-rw-r--r--man/daemon.xml949
1 files changed, 0 insertions, 949 deletions
diff --git a/man/daemon.xml b/man/daemon.xml
deleted file mode 100644
index 197138e51d..0000000000
--- a/man/daemon.xml
+++ /dev/null
@@ -1,949 +0,0 @@
-<?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 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
- SIG_DFL.</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 the daemon can never re-acquire
- a terminal again.</para></listitem>
-
- <listitem><para>Call <function>exit()</function> in the
- first child, so that only the second
- child (the actual daemon process)
- stays around. This ensures that the
- daemon process is reparented to
- init/PID 1, as all daemons should
- be.</para></listitem>
-
- <listitem><para>In the daemon process,
- connect <filename>/dev/null</filename>
- to STDIN, STDOUT,
- STDERR.</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
- at the same time it is verified 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
- clean process contexts: it is guaranteed that
- the environment block is sanitized, that the
- signal handlers and mask is reset and that no
- left-over file descriptors are passed. Daemons
- will be executed in their own session, and
- STDIN/STDOUT/STDERR connected to
- <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 SIGTERM is
- received, shut down the daemon and
- exit cleanly.</para></listitem>
-
- <listitem><para>If SIGHUP 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, via
- 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 STDERR 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 "&lt;4&gt;"
- (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 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, often there are 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
-AC_ARG_WITH([systemdsystemunitdir],
- AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
- [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
-if test "x$with_systemdsystemunitdir" != xno; then
- AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
-fi
-AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ])</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><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><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 &lt; 0.47.11-1
-if /sbin/chkconfig --level 5 foobar ; then
- /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&amp;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 AF_UNIX sockets,
- consider implementing socket-based activation
- (see above). Usually a minimal patch is
- sufficient to implement this: Extend the
- socket creation in the daemon code so that
- <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- is checked for already passed sockets
- first. If sockets are passed (i.e. when
- <function>sd_listen_fds()</function> returns a
- positive value), skip the socket creation step
- and use the passed sockets. Secondly, ensure
- that the file-system socket nodes for local
- AF_UNIX sockets used in the socket-based
- 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>
-
-</refentry>