diff options
Diffstat (limited to 'man/daemon.xml')
| -rw-r--r-- | man/daemon.xml | 700 |
1 files changed, 700 insertions, 0 deletions
diff --git a/man/daemon.xml b/man/daemon.xml new file mode 100644 index 0000000..8fa2506 --- /dev/null +++ b/man/daemon.xml @@ -0,0 +1,700 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="daemon"> + + <refentryinfo> + <title>daemon</title> + <productname>systemd</productname> + </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. (This relevant if the program — and all its dependencies — does + not carefully specify `O_NOCTTY` on each and every single `open()` call that might potentially open a + TTY device node.)</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 index='false'>/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 service manager, 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 + connected to <filename>/dev/null</filename> and standard output/error connected to the + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + logging service, 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 applicable, the daemon should notify the service manager about startup completion + or status updates via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + interface, in particular <varname>READY=1</varname> and <varname>STATUS=…</varname>. + </para></listitem> + + <listitem><para>If <constant>SIGTERM</constant> is received, shut down the daemon and exit cleanly. + A <varname>STOPPING=1</varname> notification should be sent via + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + + <listitem><para>If <constant>SIGHUP</constant> is received, reload the configuration files, if this + applies. This should be combined with notifications via + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>: + <varname>RELOADING=1</varname> and <varname>READY=1</varname>. + </para></listitem> + + <listitem><para>Provide a correct exit code from the main daemon process, as this is used by the + service manager 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 service manager'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 so on. 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 the service opens sockets or other files on it own, and those file descriptors + shall survive a restart, the daemon should store them in the service manager via + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> with + <varname>FDSTORE=1</varname>..</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. 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> + + <listitem><para>As new-style daemons are invoked without a controlling TTY (but as their own session + leaders) care should be taken to always specify <constant>O_NOCTTY</constant> on + <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry> + calls that possibly reference a TTY device node, so that no controlling TTY is accidentally + acquired.</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 use + 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 use + 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 service manager. Based on per-daemon configuration, the service manager + 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 + service manager 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 + [Install] 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 use + 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>/<constant>IPV6_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 I/O 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 I/O schedulers. If a process executed by the service manager shall not negatively impact + the amount of CPU or I/O 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 + [Install] section including installation + information for the unit file. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. To activate your service on boot, make sure to + add a <varname>WantedBy=multi-user.target</varname> or + <varname>WantedBy=graphical.target</varname> directive. To + activate your socket on boot, make sure to add + <varname>WantedBy=sockets.target</varname>. Usually, you also + want to make sure that when your service is installed, your + socket is installed too, hence add + <varname>Also=foo.socket</varname> in your service file + <filename>foo.service</filename>, for a hypothetical program + <filename>foo</filename>.</para></listitem> + + </orderedlist> + </refsect2> + + <refsect2> + <title>Installing systemd Service Files</title> + + <para>At the build installation time (e.g. <command>make + install</command> during package build), packages are + recommended to install their systemd unit files in the directory + returned by <command>pkg-config systemd + --variable=systemdsystemunitdir</command> (for system services) + or <command>pkg-config systemd + --variable=systemduserunitdir</command> (for user services). + This will make the services available in the system on explicit + request but not activate them automatically during boot. + Optionally, during package installation (e.g. <command>rpm + -i</command> by the administrator), symlinks should be created + in the systemd configuration directories via the + <command>enable</command> command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool to activate them automatically on boot.</para> + + <para>Packages using + <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry> + are recommended to use a configure script + excerpt like the following to determine the + unit installation path during source + configuration:</para> + + <programlisting>PKG_PROG_PKG_CONFIG() +AC_ARG_WITH([systemdsystemunitdir], + [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],, + [with_systemdsystemunitdir=auto]) +AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [ + def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd) + + AS_IF([test "x$def_systemdsystemunitdir" = "x"], + [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"], + [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])]) + with_systemdsystemunitdir=no], + [with_systemdsystemunitdir="$def_systemdsystemunitdir"])]) +AS_IF([test "x$with_systemdsystemunitdir" != "xno"], + [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])]) +AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</programlisting> + + <para>This snippet allows automatic + installation of the unit files on systemd + machines, and optionally allows their + installation even on machines lacking + systemd. (Modification of this snippet for the + user unit directory is left as an exercise for the + reader.)</para> + + <para>Additionally, to ensure that + <command>make distcheck</command> continues to + work, it is recommended to add the following + to the top-level <filename>Makefile.am</filename> + file in + <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based + projects:</para> + + <programlisting>AM_DISTCHECK_CONFIGURE_FLAGS = \ + --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting> + + <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para> + + <programlisting>if HAVE_SYSTEMD +systemdsystemunit_DATA = \ + foobar.socket \ + foobar.service +endif</programlisting> + + <para>In the + <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <filename>.spec</filename> file, use snippets like the following + to enable/disable the service during + installation/deinstallation. This makes use of the RPM macros + shipped along systemd. Consult the packaging guidelines of your + distribution for details and the equivalent for other package + managers.</para> + + <para>At the top of the file:</para> + + <programlisting>BuildRequires: systemd +%{?systemd_requires}</programlisting> + + <para>And as scriptlets, further down:</para> + + <programlisting>%post +%systemd_post foobar.service foobar.socket + +%preun +%systemd_preun foobar.service foobar.socket + +%postun +%systemd_postun</programlisting> + + <para>If the service shall be restarted during upgrades, replace + the <literal>%postun</literal> scriptlet above with the + following:</para> + + <programlisting>%postun +%systemd_postun_with_restart foobar.service</programlisting> + + <para>Note that <literal>%systemd_post</literal> and + <literal>%systemd_preun</literal> expect the names of all units + that are installed/removed as arguments, separated by spaces. + <literal>%systemd_postun</literal> expects no arguments. + <literal>%systemd_postun_with_restart</literal> expects the + units to restart as arguments.</para> + + <para>To facilitate upgrades from a package version that shipped + only SysV init scripts to a package version that ships both a + SysV init script and a native systemd service file, use a + fragment like the following:</para> + + <programlisting>%triggerun -- foobar < 0.47.11-1 +if /sbin/chkconfig --level 5 foobar ; then + /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || : +fi</programlisting> + + <para>Where 0.47.11-1 is the first package version that includes + the native unit file. This fragment will ensure that the first + time the unit file is installed, it will be enabled if and only + if the SysV init script is enabled, thus making sure that the + enable status is not changed. Note that + <command>chkconfig</command> is a command specific to Fedora + which can be used to check whether a SysV init script is + enabled. Other operating systems will have to use different + commands here.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Porting Existing Daemons</title> + + <para>Since new-style init systems such as systemd are compatible + with traditional SysV init systems, it is not strictly necessary + to port existing daemons to the new style. However, doing so + offers additional functionality to the daemons as well as + simplifying integration into new-style init systems.</para> + + <para>To port an existing SysV compatible daemon, the following + steps are recommended:</para> + + <orderedlist> + <listitem><para>If not already implemented, add an optional + command line switch to the daemon to disable daemonization. This + is useful not only for using the daemon in new-style init + systems, but also to ease debugging.</para></listitem> + + <listitem><para>If the daemon offers interfaces to other software running on the local system via local + <constant>AF_UNIX</constant> sockets, consider implementing socket-based activation (see above). + Usually, a minimal patch is sufficient to implement this: Extend the socket creation in the daemon code + so that + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> is + checked for already passed sockets first. If sockets are passed (i.e. when + <function>sd_listen_fds()</function> returns a positive value), skip the socket creation step and use + the passed sockets. Secondly, ensure that the file system socket nodes for local + <constant>AF_UNIX</constant> sockets used in the socket-based activation are not removed when the + daemon shuts down, if sockets have been passed. Third, if the daemon normally closes all remaining open + file descriptors as part of its initialization, the sockets passed from the service manager 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> |