| <?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+ --> |
| |
| <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 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 |
| 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 <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> |
| |
| <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 `O_NOCTTY` on `open()` 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 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 |
| [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 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>/<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 init system 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 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> |