man/daemon.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>daemon</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 220</span><hr><div class="refentry"><a name="daemon"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>daemon — Writing and packaging system daemons</p></div><div class="refsect1"><a name="idm140518024287440"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>A daemon is a service process that runs in the background
  23     and supervises the system or provides functionality to other
  24     processes. Traditionally, daemons are implemented following a
  25     scheme originating in SysV Unix. Modern daemons should follow a
  26     simpler yet more powerful scheme (here called "new-style"
  27     daemons), as implemented by
  28     <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>.
  29     This manual page covers both schemes, and in particular includes
  30     recommendations for daemons that shall be included in the systemd
  31     init system.</p><div class="refsect2"><a name="idm140518024283728"></a><h3 id="SysV Daemons">SysV Daemons<a class="headerlink" title="Permalink to this headline" href="#SysV%20Daemons">¶</a></h3><p>When a traditional SysV daemon starts, it should execute
  32       the following steps as part of the initialization. Note that
  33       these steps are unnecessary for new-style daemons (see below),
  34       and should only be implemented if compatibility with SysV is
  35       essential.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Close all open file descriptors except
  36         standard input, output, and error (i.e. the first three file
  37         descriptors 0, 1, 2). This ensures that no accidentally passed
  38         file descriptor stays around in the daemon process. On Linux,
  39         this is best implemented by iterating through
  40         <code class="filename">/proc/self/fd</code>, with a fallback of
  41         iterating from file descriptor 3 to the value returned by
  42         <code class="function">getrlimit()</code> for
  43         <code class="constant">RLIMIT_NOFILE</code>. </p></li><li class="listitem"><p>Reset all signal handlers to their default.
  44         This is best done by iterating through the available signals
  45         up to the limit of <code class="constant">_NSIG</code> and resetting
  46         them to <code class="constant">SIG_DFL</code>.</p></li><li class="listitem"><p>Reset the signal mask
  47         using
  48         <code class="function">sigprocmask()</code>.</p></li><li class="listitem"><p>Sanitize the environment block, removing or
  49         resetting environment variables that might negatively impact
  50         daemon runtime.</p></li><li class="listitem"><p>Call <code class="function">fork()</code>, to create a
  51         background process.</p></li><li class="listitem"><p>In the child, call
  52         <code class="function">setsid()</code> to detach from any terminal and
  53         create an independent session.</p></li><li class="listitem"><p>In the child, call <code class="function">fork()</code>
  54         again, to ensure that the daemon can never re-acquire a
  55         terminal again.</p></li><li class="listitem"><p>Call <code class="function">exit()</code> in the first
  56         child, so that only the second child (the actual daemon
  57         process) stays around. This ensures that the daemon process is
  58         re-parented to init/PID 1, as all daemons should
  59         be.</p></li><li class="listitem"><p>In the daemon process, connect
  60         <code class="filename">/dev/null</code> to standard input, output, and
  61         error.</p></li><li class="listitem"><p>In the daemon process, reset the umask to 0,
  62         so that the file modes passed to <code class="function">open()</code>,
  63         <code class="function">mkdir()</code> and suchlike directly control the
  64         access mode of the created files and
  65         directories.</p></li><li class="listitem"><p>In the daemon process, change the current
  66         directory to the root directory (/), in order to avoid that
  67         the daemon involuntarily blocks mount points from being
  68         unmounted.</p></li><li class="listitem"><p>In the daemon process, write the daemon PID
  69         (as returned by <code class="function">getpid()</code>) to a PID file,
  70         for example <code class="filename">/run/foobar.pid</code> (for a
  71         hypothetical daemon "foobar") to ensure that the daemon cannot
  72         be started more than once. This must be implemented in
  73         race-free fashion so that the PID file is only updated when it
  74         is verified at the same time that the PID previously stored in
  75         the PID file no longer exists or belongs to a foreign
  76         process.</p></li><li class="listitem"><p>In the daemon process, drop privileges, if
  77         possible and applicable.</p></li><li class="listitem"><p>From the daemon process, notify the original
  78         process started that initialization is complete. This can be
  79         implemented via an unnamed pipe or similar communication
  80         channel that is created before the first
  81         <code class="function">fork()</code> and hence available in both the
  82         original and the daemon process.</p></li><li class="listitem"><p>Call <code class="function">exit()</code> in the
  83         original process. The process that invoked the daemon must be
  84         able to rely on that this <code class="function">exit()</code> happens
  85         after initialization is complete and all external
  86         communication channels are established and
  87         accessible.</p></li></ol></div><p>The BSD <code class="function">daemon()</code> function should not
  88       be used, as it implements only a subset of these steps.</p><p>A daemon that needs to provide compatibility with SysV
  89       systems should implement the scheme pointed out above. However,
  90       it is recommended to make this behavior optional and
  91       configurable via a command line argument to ease debugging as
  92       well as to simplify integration into systems using
  93       systemd.</p></div><div class="refsect2"><a name="idm140518023472336"></a><h3 id="New-Style Daemons">New-Style Daemons<a class="headerlink" title="Permalink to this headline" href="#New-Style%20Daemons">¶</a></h3><p>Modern services for Linux should be implemented as
  94       new-style daemons. This makes it easier to supervise and control
  95       them at runtime and simplifies their implementation.</p><p>For developing a new-style daemon, none of the
  96       initialization steps recommended for SysV daemons need to be
  97       implemented. New-style init systems such as systemd make all of
  98       them redundant. Moreover, since some of these steps interfere
  99       with process monitoring, file descriptor passing and other
 100       functionality of the init system, it is recommended not to
 101       execute them when run as new-style service.</p><p>Note that new-style init systems guarantee execution of
 102       daemon processes in a clean process context: it is guaranteed
 103       that the environment block is sanitized, that the signal
 104       handlers and mask is reset and that no left-over file
 105       descriptors are passed. Daemons will be executed in their own
 106       session, with standard input/output/error connected to
 107       <code class="filename">/dev/null</code> unless otherwise configured. The
 108       umask is reset.
 109       </p><p>It is recommended for new-style daemons to implement the
 110       following:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>If <code class="constant">SIGTERM</code> is received,
 111         shut down the daemon and exit cleanly.</p></li><li class="listitem"><p>If <code class="constant">SIGHUP</code> is received,
 112         reload the configuration files, if this
 113         applies.</p></li><li class="listitem"><p>Provide a correct exit code from the main
 114         daemon process, as this is used by the init system to detect
 115         service errors and problems. It is recommended to follow the
 116         exit code scheme as defined in the <a class="ulink" href="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html" target="_top">LSB
 117         recommendations for SysV init
 118         scripts</a>.</p></li><li class="listitem"><p>If possible and applicable, expose the
 119         daemon's control interface via the D-Bus IPC system and grab a
 120         bus name as last step of initialization.</p></li><li class="listitem"><p>For integration in systemd, provide a
 121         <code class="filename">.service</code> unit file that carries
 122         information about starting, stopping and otherwise maintaining
 123         the daemon. See
 124         <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
 125         for details.</p></li><li class="listitem"><p>As much as possible, rely on the init system's
 126         functionality to limit the access of the daemon to files,
 127         services and other resources, i.e. in the case of systemd,
 128         rely on systemd's resource limit control instead of
 129         implementing your own, rely on systemd's privilege dropping
 130         code instead of implementing it in the daemon, and similar.
 131         See
 132         <a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>
 133         for the available controls.</p></li><li class="listitem"><p>If D-Bus is used, make your daemon
 134         bus-activatable by supplying a D-Bus service activation
 135         configuration file. This has multiple advantages: your daemon
 136         may be started lazily on-demand; it may be started in parallel
 137         to other daemons requiring it -- which maximizes
 138         parallelization and boot-up speed; your daemon can be
 139         restarted on failure without losing any bus requests, as the
 140         bus queues requests for activatable services. See below for
 141         details.</p></li><li class="listitem"><p>If your daemon provides services to other
 142         local processes or remote clients via a socket, it should be
 143         made socket-activatable following the scheme pointed out
 144         below. Like D-Bus activation, this enables on-demand starting
 145         of services as well as it allows improved parallelization of
 146         service start-up. Also, for state-less protocols (such as
 147         syslog, DNS), a daemon implementing socket-based activation
 148         can be restarted without losing a single request. See below
 149         for details.</p></li><li class="listitem"><p>If applicable, a daemon should notify the init
 150         system about startup completion or status updates via the
 151         <a href="sd_notify.html"><span class="citerefentry"><span class="refentrytitle">sd_notify</span>(3)</span></a>
 152         interface.</p></li><li class="listitem"><p>Instead of using the
 153         <code class="function">syslog()</code> call to log directly to the
 154         system syslog service, a new-style daemon may choose to simply
 155         log to standard error via <code class="function">fprintf()</code>,
 156         which is then forwarded to syslog by the init system. If log
 157         levels are necessary, these can be encoded by prefixing
 158         individual log lines with strings like
 159         "<code class="literal">&lt;4&gt;</code>" (for log level 4 "WARNING" in the
 160         syslog priority scheme), following a similar style as the
 161         Linux kernel's <code class="function">printk()</code> level system. For
 162         details, see
 163         <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>
 164         and
 165         <a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>.</p></li></ol></div><p>These recommendations are similar but not identical to the
 166       <a class="ulink" href="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html" target="_top">Apple
 167       MacOS X Daemon Requirements</a>.</p></div></div><div class="refsect1"><a name="idm140518023449360"></a><h2 id="Activation">Activation<a class="headerlink" title="Permalink to this headline" href="#Activation">¶</a></h2><p>New-style init systems provide multiple additional
 168     mechanisms to activate services, as detailed below. It is common
 169     that services are configured to be activated via more than one
 170     mechanism at the same time. An example for systemd:
 171     <code class="filename">bluetoothd.service</code> might get activated either
 172     when Bluetooth hardware is plugged in, or when an application
 173     accesses its programming interfaces via D-Bus. Or, a print server
 174     daemon might get activated when traffic arrives at an IPP port, or
 175     when a printer is plugged in, or when a file is queued in the
 176     printer spool directory. Even for services that are intended to be
 177     started on system bootup unconditionally, it is a good idea to
 178     implement some of the various activation schemes outlined below,
 179     in order to maximize parallelization. If a daemon implements a
 180     D-Bus service or listening socket, implementing the full bus and
 181     socket activation scheme allows starting of the daemon with its
 182     clients in parallel (which speeds up boot-up), since all its
 183     communication channels are established already, and no request is
 184     lost because client requests will be queued by the bus system (in
 185     case of D-Bus) or the kernel (in case of sockets) until the
 186     activation is completed.</p><div class="refsect2"><a name="idm140518023446432"></a><h3 id="Activation on Boot">Activation on Boot<a class="headerlink" title="Permalink to this headline" href="#Activation%20on%20Boot">¶</a></h3><p>Old-style daemons are usually activated exclusively on
 187       boot (and manually by the administrator) via SysV init scripts,
 188       as detailed in the <a class="ulink" href="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html" target="_top">LSB
 189       Linux Standard Base Core Specification</a>. This method of
 190       activation is supported ubiquitously on Linux init systems, both
 191       old-style and new-style systems. Among other issues, SysV init
 192       scripts have the disadvantage of involving shell scripts in the
 193       boot process. New-style init systems generally employ updated
 194       versions of activation, both during boot-up and during runtime
 195       and using more minimal service description files.</p><p>In systemd, if the developer or administrator wants to
 196       make sure that a service or other unit is activated
 197       automatically on boot, it is recommended to place a symlink to
 198       the unit file in the <code class="filename">.wants/</code> directory of
 199       either <code class="filename">multi-user.target</code> or
 200       <code class="filename">graphical.target</code>, which are normally used
 201       as boot targets at system startup. See
 202       <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
 203       for details about the <code class="filename">.wants/</code> directories,
 204       and
 205       <a href="systemd.special.html"><span class="citerefentry"><span class="refentrytitle">systemd.special</span>(7)</span></a>
 206       for details about the two boot targets.</p></div><div class="refsect2"><a name="idm140518023439216"></a><h3 id="Socket-Based Activation">Socket-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Socket-Based%20Activation">¶</a></h3><p>In order to maximize the possible parallelization and
 207       robustness and simplify configuration and development, it is
 208       recommended for all new-style daemons that communicate via
 209       listening sockets to employ socket-based activation. In a
 210       socket-based activation scheme, the creation and binding of the
 211       listening socket as primary communication channel of daemons to
 212       local (and sometimes remote) clients is moved out of the daemon
 213       code and into the init system. Based on per-daemon
 214       configuration, the init system installs the sockets and then
 215       hands them off to the spawned process as soon as the respective
 216       daemon is to be started. Optionally, activation of the service
 217       can be delayed until the first inbound traffic arrives at the
 218       socket to implement on-demand activation of daemons. However,
 219       the primary advantage of this scheme is that all providers and
 220       all consumers of the sockets can be started in parallel as soon
 221       as all sockets are established. In addition to that, daemons can
 222       be restarted with losing only a minimal number of client
 223       transactions, or even any client request at all (the latter is
 224       particularly true for state-less protocols, such as DNS or
 225       syslog), because the socket stays bound and accessible during
 226       the restart, and all requests are queued while the daemon cannot
 227       process them.</p><p>New-style daemons which support socket activation must be
 228       able to receive their sockets from the init system instead of
 229       creating and binding them themselves. For details about the
 230       programming interfaces for this scheme provided by systemd, see
 231       <a href="sd_listen_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_listen_fds</span>(3)</span></a>
 232       and
 233       <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>.
 234       For details about porting existing daemons to socket-based
 235       activation, see below. With minimal effort, it is possible to
 236       implement socket-based activation in addition to traditional
 237       internal socket creation in the same codebase in order to
 238       support both new-style and old-style init systems from the same
 239       daemon binary.</p><p>systemd implements socket-based activation via
 240       <code class="filename">.socket</code> units, which are described in
 241       <a href="systemd.socket.html"><span class="citerefentry"><span class="refentrytitle">systemd.socket</span>(5)</span></a>.
 242       When configuring socket units for socket-based activation, it is
 243       essential that all listening sockets are pulled in by the
 244       special target unit <code class="filename">sockets.target</code>. It is
 245       recommended to place a
 246       <code class="varname">WantedBy=sockets.target</code> directive in the
 247       "<code class="literal">[Install]</code>" section to automatically add such a
 248       dependency on installation of a socket unit. Unless
 249       <code class="varname">DefaultDependencies=no</code> is set, the necessary
 250       ordering dependencies are implicitly created for all socket
 251       units. For more information about
 252       <code class="filename">sockets.target</code>, see
 253       <a href="systemd.special.html"><span class="citerefentry"><span class="refentrytitle">systemd.special</span>(7)</span></a>.
 254       It is not necessary or recommended to place any additional
 255       dependencies on socket units (for example from
 256       <code class="filename">multi-user.target</code> or suchlike) when one is
 257       installed in <code class="filename">sockets.target</code>.</p></div><div class="refsect2"><a name="idm140518023427040"></a><h3 id="Bus-Based Activation">Bus-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Bus-Based%20Activation">¶</a></h3><p>When the D-Bus IPC system is used for communication with
 258       clients, new-style daemons should employ bus activation so that
 259       they are automatically activated when a client application
 260       accesses their IPC interfaces. This is configured in D-Bus
 261       service files (not to be confused with systemd service unit
 262       files!). To ensure that D-Bus uses systemd to start-up and
 263       maintain the daemon, use the <code class="varname">SystemdService=</code>
 264       directive in these service files to configure the matching
 265       systemd service for a D-Bus service. e.g.: For a D-Bus service
 266       whose D-Bus activation file is named
 267       <code class="filename">org.freedesktop.RealtimeKit.service</code>, make
 268       sure to set
 269       <code class="varname">SystemdService=rtkit-daemon.service</code> in that
 270       file to bind it to the systemd service
 271       <code class="filename">rtkit-daemon.service</code>. This is needed to
 272       make sure that the daemon is started in a race-free fashion when
 273       activated via multiple mechanisms simultaneously.</p></div><div class="refsect2"><a name="idm140518028177120"></a><h3 id="Device-Based Activation">Device-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Device-Based%20Activation">¶</a></h3><p>Often, daemons that manage a particular type of hardware
 274       should be activated only when the hardware of the respective
 275       kind is plugged in or otherwise becomes available. In a
 276       new-style init system, it is possible to bind activation to
 277       hardware plug/unplug events. In systemd, kernel devices
 278       appearing in the sysfs/udev device tree can be exposed as units
 279       if they are tagged with the string "<code class="literal">systemd</code>".
 280       Like any other kind of unit, they may then pull in other units
 281       when activated (i.e. plugged in) and thus implement device-based
 282       activation. systemd dependencies may be encoded in the udev
 283       database via the <code class="varname">SYSTEMD_WANTS=</code> property. See
 284       <a href="systemd.device.html"><span class="citerefentry"><span class="refentrytitle">systemd.device</span>(5)</span></a>
 285       for details. Often, it is nicer to pull in services from devices
 286       only indirectly via dedicated targets. Example: Instead of
 287       pulling in <code class="filename">bluetoothd.service</code> from all the
 288       various bluetooth dongles and other hardware available, pull in
 289       bluetooth.target from them and
 290       <code class="filename">bluetoothd.service</code> from that target. This
 291       provides for nicer abstraction and gives administrators the
 292       option to enable <code class="filename">bluetoothd.service</code> via
 293       controlling a <code class="filename">bluetooth.target.wants/</code>
 294       symlink uniformly with a command like <span class="command"><strong>enable</strong></span>
 295       of
 296       <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>
 297       instead of manipulating the udev ruleset.</p></div><div class="refsect2"><a name="idm140518023406288"></a><h3 id="Path-Based Activation">Path-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Path-Based%20Activation">¶</a></h3><p>Often, runtime of daemons processing spool files or
 298       directories (such as a printing system) can be delayed until
 299       these file system objects change state, or become non-empty.
 300       New-style init systems provide a way to bind service activation
 301       to file system changes. systemd implements this scheme via
 302       path-based activation configured in <code class="filename">.path</code>
 303       units, as outlined in
 304       <a href="systemd.path.html"><span class="citerefentry"><span class="refentrytitle">systemd.path</span>(5)</span></a>.</p></div><div class="refsect2"><a name="idm140518023403360"></a><h3 id="Timer-Based Activation">Timer-Based Activation<a class="headerlink" title="Permalink to this headline" href="#Timer-Based%20Activation">¶</a></h3><p>Some daemons that implement clean-up jobs that are
 305       intended to be executed in regular intervals benefit from
 306       timer-based activation. In systemd, this is implemented via
 307       <code class="filename">.timer</code> units, as described in
 308       <a href="systemd.timer.html"><span class="citerefentry"><span class="refentrytitle">systemd.timer</span>(5)</span></a>.</p></div><div class="refsect2"><a name="idm140518023400608"></a><h3 id="Other Forms of Activation">Other Forms of Activation<a class="headerlink" title="Permalink to this headline" href="#Other%20Forms%20of%20Activation">¶</a></h3><p>Other forms of activation have been suggested and
 309       implemented in some systems. However, there are often simpler or
 310       better alternatives, or they can be put together of combinations
 311       of the schemes above. Example: Sometimes, it appears useful to
 312       start daemons or <code class="filename">.socket</code> units when a
 313       specific IP address is configured on a network interface,
 314       because network sockets shall be bound to the address. However,
 315       an alternative to implement this is by utilizing the Linux
 316       <code class="constant">IP_FREEBIND</code> socket option, as accessible
 317       via <code class="varname">FreeBind=yes</code> in systemd socket files (see
 318       <a href="systemd.socket.html"><span class="citerefentry"><span class="refentrytitle">systemd.socket</span>(5)</span></a>
 319       for details). This option, when enabled, allows sockets to be
 320       bound to a non-local, not configured IP address, and hence
 321       allows bindings to a particular IP address before it actually
 322       becomes available, making such an explicit dependency to the
 323       configured address redundant. Another often suggested trigger
 324       for service activation is low system load. However, here too, a
 325       more convincing approach might be to make proper use of features
 326       of the operating system, in particular, the CPU or IO scheduler
 327       of Linux. Instead of scheduling jobs from userspace based on
 328       monitoring the OS scheduler, it is advisable to leave the
 329       scheduling of processes to the OS scheduler itself. systemd
 330       provides fine-grained access to the CPU and IO schedulers. If a
 331       process executed by the init system shall not negatively impact
 332       the amount of CPU or IO bandwidth available to other processes,
 333       it should be configured with
 334       <code class="varname">CPUSchedulingPolicy=idle</code> and/or
 335       <code class="varname">IOSchedulingClass=idle</code>. Optionally, this may
 336       be combined with timer-based activation to schedule background
 337       jobs during runtime and with minimal impact on the system, and
 338       remove it from the boot phase itself.</p></div></div><div class="refsect1"><a name="idm140518023394624"></a><h2 id="Integration with Systemd">Integration with Systemd<a class="headerlink" title="Permalink to this headline" href="#Integration%20with%20Systemd">¶</a></h2><div class="refsect2"><a name="idm140518023393984"></a><h3 id="Writing Systemd Unit Files">Writing Systemd Unit Files<a class="headerlink" title="Permalink to this headline" href="#Writing%20Systemd%20Unit%20Files">¶</a></h3><p>When writing systemd unit files, it is recommended to
 339       consider the following suggestions:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>If possible, do not use the
 340         <code class="varname">Type=forking</code> setting in service files. But
 341         if you do, make sure to set the PID file path using
 342         <code class="varname">PIDFile=</code>. See
 343         <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>
 344         for details.</p></li><li class="listitem"><p>If your daemon registers a D-Bus name on the
 345         bus, make sure to use <code class="varname">Type=dbus</code> in the
 346         service file if possible.</p></li><li class="listitem"><p>Make sure to set a good human-readable
 347         description string with
 348         <code class="varname">Description=</code>.</p></li><li class="listitem"><p>Do not disable
 349         <code class="varname">DefaultDependencies=</code>, unless you really
 350         know what you do and your unit is involved in early boot or
 351         late system shutdown.</p></li><li class="listitem"><p>Normally, little if any dependencies should
 352         need to be defined explicitly. However, if you do configure
 353         explicit dependencies, only refer to unit names listed on
 354         <a href="systemd.special.html"><span class="citerefentry"><span class="refentrytitle">systemd.special</span>(7)</span></a>
 355         or names introduced by your own package to keep the unit file
 356         operating system-independent.</p></li><li class="listitem"><p>Make sure to include an
 357         "<code class="literal">[Install]</code>" section including installation
 358         information for the unit file. See
 359         <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
 360         for details. To activate your service on boot, make sure to
 361         add a <code class="varname">WantedBy=multi-user.target</code> or
 362         <code class="varname">WantedBy=graphical.target</code> directive. To
 363         activate your socket on boot, make sure to add
 364         <code class="varname">WantedBy=sockets.target</code>. Usually, you also
 365         want to make sure that when your service is installed, your
 366         socket is installed too, hence add
 367         <code class="varname">Also=foo.socket</code> in your service file
 368         <code class="filename">foo.service</code>, for a hypothetical program
 369         <code class="filename">foo</code>.</p></li></ol></div></div><div class="refsect2"><a name="idm140518023379936"></a><h3 id="Installing Systemd Service Files">Installing Systemd Service Files<a class="headerlink" title="Permalink to this headline" href="#Installing%20Systemd%20Service%20Files">¶</a></h3><p>At the build installation time (e.g. <span class="command"><strong>make
 370       install</strong></span> during package build), packages are
 371       recommended to install their systemd unit files in the directory
 372       returned by <span class="command"><strong>pkg-config systemd
 373       --variable=systemdsystemunitdir</strong></span> (for system services)
 374       or <span class="command"><strong>pkg-config systemd
 375       --variable=systemduserunitdir</strong></span> (for user services).
 376       This will make the services available in the system on explicit
 377       request but not activate them automatically during boot.
 378       Optionally, during package installation (e.g. <span class="command"><strong>rpm
 379       -i</strong></span> by the administrator), symlinks should be created
 380       in the systemd configuration directories via the
 381       <span class="command"><strong>enable</strong></span> command of the
 382       <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>
 383       tool to activate them automatically on boot.</p><p>Packages using
 384       <a href="http://linux.die.net/man/1/autoconf"><span class="citerefentry"><span class="refentrytitle">autoconf</span>(1)</span></a>
 385       are recommended to use a configure script
 386       excerpt like the following to determine the
 387       unit installation path during source
 388       configuration:</p><pre class="programlisting">PKG_PROG_PKG_CONFIG
 389 AC_ARG_WITH([systemdsystemunitdir],
 390      [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],,
 391      [with_systemdsystemunitdir=auto])
 392 AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [
 393      def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)
 394
 395      AS_IF([test "x$def_systemdsystemunitdir" = "x"],
 396    [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"],
 397     [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])])
 398     with_systemdsystemunitdir=no],
 399    [with_systemdsystemunitdir="$def_systemdsystemunitdir"])])
 400 AS_IF([test "x$with_systemdsystemunitdir" != "xno"],
 401       [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])])
 402 AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</pre><p>This snippet allows automatic
 403       installation of the unit files on systemd
 404       machines, and optionally allows their
 405       installation even on machines lacking
 406       systemd. (Modification of this snippet for the
 407       user unit directory is left as an exercise for the
 408       reader.)</p><p>Additionally, to ensure that
 409       <span class="command"><strong>make distcheck</strong></span> continues to
 410       work, it is recommended to add the following
 411       to the top-level <code class="filename">Makefile.am</code>
 412       file in
 413       <a href="http://linux.die.net/man/1/automake"><span class="citerefentry"><span class="refentrytitle">automake</span>(1)</span></a>-based
 414       projects:</p><pre class="programlisting">DISTCHECK_CONFIGURE_FLAGS = \
 415   --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</pre><p>Finally, unit files should be installed in the system with an automake excerpt like the following:</p><pre class="programlisting">if HAVE_SYSTEMD
 416 systemdsystemunit_DATA = \
 417   foobar.socket \
 418   foobar.service
 419 endif</pre><p>In the
 420       <a href="http://linux.die.net/man/8/rpm"><span class="citerefentry"><span class="refentrytitle">rpm</span>(8)</span></a>
 421       <code class="filename">.spec</code> file, use snippets like the following
 422       to enable/disable the service during
 423       installation/deinstallation. This makes use of the RPM macros
 424       shipped along systemd. Consult the packaging guidelines of your
 425       distribution for details and the equivalent for other package
 426       managers.</p><p>At the top of the file:</p><pre class="programlisting">BuildRequires: systemd
 427 %{?systemd_requires}</pre><p>And as scriptlets, further down:</p><pre class="programlisting">%post
 428 %systemd_post foobar.service foobar.socket
 429
 430 %preun
 431 %systemd_preun foobar.service foobar.socket
 432
 433 %postun
 434 %systemd_postun</pre><p>If the service shall be restarted during upgrades, replace
 435       the "<code class="literal">%postun</code>" scriptlet above with the
 436       following:</p><pre class="programlisting">%postun
 437 %systemd_postun_with_restart foobar.service</pre><p>Note that "<code class="literal">%systemd_post</code>" and
 438       "<code class="literal">%systemd_preun</code>" expect the names of all units
 439       that are installed/removed as arguments, separated by spaces.
 440       "<code class="literal">%systemd_postun</code>" expects no arguments.
 441       "<code class="literal">%systemd_postun_with_restart</code>" expects the
 442       units to restart as arguments.</p><p>To facilitate upgrades from a package version that shipped
 443       only SysV init scripts to a package version that ships both a
 444       SysV init script and a native systemd service file, use a
 445       fragment like the following:</p><pre class="programlisting">%triggerun -- foobar &lt; 0.47.11-1
 446 if /sbin/chkconfig --level 5 foobar ; then
 447   /bin/systemctl --no-reload enable foobar.service foobar.socket &gt;/dev/null 2&gt;&amp;1 || :
 448 fi</pre><p>Where 0.47.11-1 is the first package version that includes
 449       the native unit file. This fragment will ensure that the first
 450       time the unit file is installed, it will be enabled if and only
 451       if the SysV init script is enabled, thus making sure that the
 452       enable status is not changed. Note that
 453       <span class="command"><strong>chkconfig</strong></span> is a command specific to Fedora
 454       which can be used to check whether a SysV init script is
 455       enabled. Other operating systems will have to use different
 456       commands here.</p></div></div><div class="refsect1"><a name="idm140518023353504"></a><h2 id="Porting Existing Daemons">Porting Existing Daemons<a class="headerlink" title="Permalink to this headline" href="#Porting%20Existing%20Daemons">¶</a></h2><p>Since new-style init systems such as systemd are compatible
 457     with traditional SysV init systems, it is not strictly necessary
 458     to port existing daemons to the new style. However, doing so
 459     offers additional functionality to the daemons as well as
 460     simplifying integration into new-style init systems.</p><p>To port an existing SysV compatible daemon, the following
 461     steps are recommended:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>If not already implemented, add an optional
 462       command line switch to the daemon to disable daemonization. This
 463       is useful not only for using the daemon in new-style init
 464       systems, but also to ease debugging.</p></li><li class="listitem"><p>If the daemon offers interfaces to other
 465       software running on the local system via local
 466       <code class="constant">AF_UNIX</code> sockets, consider implementing
 467       socket-based activation (see above). Usually, a minimal patch is
 468       sufficient to implement this: Extend the socket creation in the
 469       daemon code so that
 470       <a href="sd_listen_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_listen_fds</span>(3)</span></a>
 471       is checked for already passed sockets first. If sockets are
 472       passed (i.e. when <code class="function">sd_listen_fds()</code> returns a
 473       positive value), skip the socket creation step and use the
 474       passed sockets. Secondly, ensure that the file system socket
 475       nodes for local <code class="constant">AF_UNIX</code> sockets used in the
 476       socket-based activation are not removed when the daemon shuts
 477       down, if sockets have been passed. Third, if the daemon normally
 478       closes all remaining open file descriptors as part of its
 479       initialization, the sockets passed from the init system must be
 480       spared. Since new-style init systems guarantee that no left-over
 481       file descriptors are passed to executed processes, it might be a
 482       good choice to simply skip the closing of all remaining open
 483       file descriptors if sockets are passed.</p></li><li class="listitem"><p>Write and install a systemd unit file for the
 484       service (and the sockets if socket-based activation is used, as
 485       well as a path unit file, if the daemon processes a spool
 486       directory), see above for details.</p></li><li class="listitem"><p>If the daemon exposes interfaces via D-Bus,
 487       write and install a D-Bus activation file for the service, see
 488       above for details.</p></li></ol></div></div><div class="refsect1"><a name="idm140518023344640"></a><h2 id="Placing Daemon Data">Placing Daemon Data<a class="headerlink" title="Permalink to this headline" href="#Placing%20Daemon%20Data">¶</a></h2><p>It is recommended to follow the general guidelines for
 489     placing package files, as discussed in
 490     <a href="file-hierarchy.html"><span class="citerefentry"><span class="refentrytitle">file-hierarchy</span>(7)</span></a>.</p></div><div class="refsect1"><a name="idm140518023342608"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
 491       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
 492       <a href="sd-daemon.html"><span class="citerefentry"><span class="refentrytitle">sd-daemon</span>(3)</span></a>,
 493       <a href="sd_listen_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_listen_fds</span>(3)</span></a>,
 494       <a href="sd_notify.html"><span class="citerefentry"><span class="refentrytitle">sd_notify</span>(3)</span></a>,
 495       <a href="daemon.html"><span class="citerefentry"><span class="refentrytitle">daemon</span>(3)</span></a>,
 496       <a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>,
 497       <a href="file-hierarchy.html"><span class="citerefentry"><span class="refentrytitle">file-hierarchy</span>(7)</span></a>
 498     </p></div></div></body></html>