diff options
| author | Anthony G. Basile <blueness@gentoo.org> | 2012-11-15 10:33:16 -0500 |
|---|---|---|
| committer | Anthony G. Basile <blueness@gentoo.org> | 2012-11-15 10:33:16 -0500 |
| commit | 7d4a62f8c1404ed426500b97af03d4ef8d034a71 (patch) | |
| tree | 2436cd4f0460a3a3d589875d4ffba55556f3c582 /man/daemon.xml | |
| parent | 2944f347d087ff24ec808e4b70fe104a772a97a0 (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.xml | 949 |
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 "<4>" - (for log priority 4 "WARNING" in the - syslog priority scheme), following a - similar style as the Linux kernel's - <function>printk()</function> priority system. In fact, - using this style of logging also - enables the init system to optionally - direct all application logging to the - kernel log buffer (kmsg), as - accessible via - <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This - kind of logging may be enabled by - setting - <varname>StandardError=syslog</varname> - in the service unit file. For details - see - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - </orderedlist> - - <para>These recommendations are similar but - not identical to the <ulink - url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">Apple - MacOS X Daemon Requirements</ulink>.</para> - </refsect2> - - </refsect1> - <refsect1> - <title>Activation</title> - - <para>New-style init systems provide multiple - additional mechanisms to activate services, as - detailed below. It is common that services are - configured to be activated via more than one mechanism - at the same time. An example for systemd: - <filename>bluetoothd.service</filename> might get - activated either when Bluetooth hardware is plugged - in, or when an application accesses its programming - interfaces via D-Bus. Or, a print server daemon might - get activated when traffic arrives at an IPP port, or - when a printer is plugged in, or when a file is queued - in the printer spool directory. Even for services that - are intended to be started on system bootup - unconditionally it is a good idea to implement some of - the various activation schemes outlined below, in - order to maximize parallelization: if a daemon - implements a D-Bus service or listening socket, - implementing the full bus and socket activation scheme - allows starting of the daemon with its clients in - parallel (which speeds up boot-up), since all its - communication channels are established already, and no - request is lost because client requests will be queued - by the bus system (in case of D-Bus) or the kernel (in - case of sockets), until the activation is - completed.</para> - - <refsect2> - <title>Activation on Boot</title> - - <para>Old-style daemons are usually activated - exclusively on boot (and manually by the - administrator) via SysV init scripts, as - detailed in the <ulink - url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB - Linux Standard Base Core - Specification</ulink>. This method of - activation is supported ubiquitously on Linux - init systems, both old-style and new-style - systems. Among other issues SysV init scripts - have the disadvantage of involving shell - scripts in the boot process. New-style init - systems generally employ updated versions of - activation, both during boot-up and during - runtime and using more minimal service - description files.</para> - - <para>In systemd, if the developer or - administrator wants to make sure 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 < 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 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> |