man/daemon.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="daemon">
  25
  26   <refentryinfo>
  27     <title>daemon</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>daemon</refentrytitle>
  42     <manvolnum>7</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>daemon</refname>
  47     <refpurpose>Writing and packaging system daemons</refpurpose>
  48   </refnamediv>
  49
  50   <refsect1>
  51     <title>Description</title>
  52
  53     <para>A daemon is a service process that runs in the background
  54     and supervises the system or provides functionality to other
  55     processes. Traditionally, daemons are implemented following a
  56     scheme originating in SysV Unix. Modern daemons should follow a
  57     simpler yet more powerful scheme (here called "new-style"
  58     daemons), as implemented by
  59     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  60     This manual page covers both schemes, and in particular includes
  61     recommendations for daemons that shall be included in the systemd
  62     init system.</para>
  63
  64     <refsect2>
  65       <title>SysV Daemons</title>
  66
  67       <para>When a traditional SysV daemon starts, it should execute
  68       the following steps as part of the initialization. Note that
  69       these steps are unnecessary for new-style daemons (see below),
  70       and should only be implemented if compatibility with SysV is
  71       essential.</para>
  72
  73       <orderedlist>
  74         <listitem><para>Close all open file descriptors except
  75         standard input, output, and error (i.e. the first three file
  76         descriptors 0, 1, 2). This ensures that no accidentally passed
  77         file descriptor stays around in the daemon process. On Linux,
  78         this is best implemented by iterating through
  79         <filename>/proc/self/fd</filename>, with a fallback of
  80         iterating from file descriptor 3 to the value returned by
  81         <function>getrlimit()</function> for
  82         <constant>RLIMIT_NOFILE</constant>. </para></listitem>
  83
  84         <listitem><para>Reset all signal handlers to their default.
  85         This is best done by iterating through the available signals
  86         up to the limit of <constant>_NSIG</constant> and resetting
  87         them to <constant>SIG_DFL</constant>.</para></listitem>
  88
  89         <listitem><para>Reset the signal mask
  90         using
  91         <function>sigprocmask()</function>.</para></listitem>
  92
  93         <listitem><para>Sanitize the environment block, removing or
  94         resetting environment variables that might negatively impact
  95         daemon runtime.</para></listitem>
  96
  97         <listitem><para>Call <function>fork()</function>, to create a
  98         background process.</para></listitem>
  99
 100         <listitem><para>In the child, call
 101         <function>setsid()</function> to detach from any terminal and
 102         create an independent session.</para></listitem>
 103
 104         <listitem><para>In the child, call <function>fork()</function>
 105         again, to ensure that the daemon can never re-acquire a
 106         terminal again.</para></listitem>
 107
 108         <listitem><para>Call <function>exit()</function> in the first
 109         child, so that only the second child (the actual daemon
 110         process) stays around. This ensures that the daemon process is
 111         re-parented to init/PID 1, as all daemons should
 112         be.</para></listitem>
 113
 114         <listitem><para>In the daemon process, connect
 115         <filename>/dev/null</filename> to standard input, output, and
 116         error.</para></listitem>
 117
 118         <listitem><para>In the daemon process, reset the umask to 0,
 119         so that the file modes passed to <function>open()</function>,
 120         <function>mkdir()</function> and suchlike directly control the
 121         access mode of the created files and
 122         directories.</para></listitem>
 123
 124         <listitem><para>In the daemon process, change the current
 125         directory to the root directory (/), in order to avoid that
 126         the daemon involuntarily blocks mount points from being
 127         unmounted.</para></listitem>
 128
 129         <listitem><para>In the daemon process, write the daemon PID
 130         (as returned by <function>getpid()</function>) to a PID file,
 131         for example <filename>/run/foobar.pid</filename> (for a
 132         hypothetical daemon "foobar") to ensure that the daemon cannot
 133         be started more than once. This must be implemented in
 134         race-free fashion so that the PID file is only updated when it
 135         is verified at the same time that the PID previously stored in
 136         the PID file no longer exists or belongs to a foreign
 137         process.</para></listitem>
 138
 139         <listitem><para>In the daemon process, drop privileges, if
 140         possible and applicable.</para></listitem>
 141
 142         <listitem><para>From the daemon process, notify the original
 143         process started that initialization is complete. This can be
 144         implemented via an unnamed pipe or similar communication
 145         channel that is created before the first
 146         <function>fork()</function> and hence available in both the
 147         original and the daemon process.</para></listitem>
 148
 149         <listitem><para>Call <function>exit()</function> in the
 150         original process. The process that invoked the daemon must be
 151         able to rely on that this <function>exit()</function> happens
 152         after initialization is complete and all external
 153         communication channels are established and
 154         accessible.</para></listitem>
 155       </orderedlist>
 156
 157       <para>The BSD <function>daemon()</function> function should not
 158       be used, as it implements only a subset of these steps.</para>
 159
 160       <para>A daemon that needs to provide compatibility with SysV
 161       systems should implement the scheme pointed out above. However,
 162       it is recommended to make this behavior optional and
 163       configurable via a command line argument to ease debugging as
 164       well as to simplify integration into systems using
 165       systemd.</para>
 166     </refsect2>
 167
 168     <refsect2>
 169       <title>New-Style Daemons</title>
 170
 171       <para>Modern services for Linux should be implemented as
 172       new-style daemons. This makes it easier to supervise and control
 173       them at runtime and simplifies their implementation.</para>
 174
 175       <para>For developing a new-style daemon, none of the
 176       initialization steps recommended for SysV daemons need to be
 177       implemented. New-style init systems such as systemd make all of
 178       them redundant. Moreover, since some of these steps interfere
 179       with process monitoring, file descriptor passing and other
 180       functionality of the init system, it is recommended not to
 181       execute them when run as new-style service.</para>
 182
 183       <para>Note that new-style init systems guarantee execution of
 184       daemon processes in a clean process context: it is guaranteed
 185       that the environment block is sanitized, that the signal
 186       handlers and mask is reset and that no left-over file
 187       descriptors are passed. Daemons will be executed in their own
 188       session, with standard input/output/error connected to
 189       <filename>/dev/null</filename> unless otherwise configured. The
 190       umask is reset.
 191       </para>
 192
 193       <para>It is recommended for new-style daemons to implement the
 194       following:</para>
 195
 196       <orderedlist>
 197         <listitem><para>If <constant>SIGTERM</constant> is received,
 198         shut down the daemon and exit cleanly.</para></listitem>
 199
 200         <listitem><para>If <constant>SIGHUP</constant> is received,
 201         reload the configuration files, if this
 202         applies.</para></listitem>
 203
 204         <listitem><para>Provide a correct exit code from the main
 205         daemon process, as this is used by the init system to detect
 206         service errors and problems. It is recommended to follow the
 207         exit code scheme as defined in the <ulink
 208         url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
 209         recommendations for SysV init
 210         scripts</ulink>.</para></listitem>
 211
 212         <listitem><para>If possible and applicable, expose the
 213         daemon's control interface via the D-Bus IPC system and grab a
 214         bus name as last step of initialization.</para></listitem>
 215
 216         <listitem><para>For integration in systemd, provide a
 217         <filename>.service</filename> unit file that carries
 218         information about starting, stopping and otherwise maintaining
 219         the daemon. See
 220         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 221         for details.</para></listitem>
 222
 223         <listitem><para>As much as possible, rely on the init system's
 224         functionality to limit the access of the daemon to files,
 225         services and other resources, i.e. in the case of systemd,
 226         rely on systemd's resource limit control instead of
 227         implementing your own, rely on systemd's privilege dropping
 228         code instead of implementing it in the daemon, and similar.
 229         See
 230         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 231         for the available controls.</para></listitem>
 232
 233         <listitem><para>If D-Bus is used, make your daemon
 234         bus-activatable by supplying a D-Bus service activation
 235         configuration file. This has multiple advantages: your daemon
 236         may be started lazily on-demand; it may be started in parallel
 237         to other daemons requiring it -- which maximizes
 238         parallelization and boot-up speed; your daemon can be
 239         restarted on failure without losing any bus requests, as the
 240         bus queues requests for activatable services. See below for
 241         details.</para></listitem>
 242
 243         <listitem><para>If your daemon provides services to other
 244         local processes or remote clients via a socket, it should be
 245         made socket-activatable following the scheme pointed out
 246         below. Like D-Bus activation, this enables on-demand starting
 247         of services as well as it allows improved parallelization of
 248         service start-up. Also, for state-less protocols (such as
 249         syslog, DNS), a daemon implementing socket-based activation
 250         can be restarted without losing a single request. See below
 251         for details.</para></listitem>
 252
 253         <listitem><para>If applicable, a daemon should notify the init
 254         system about startup completion or status updates via the
 255         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 256         interface.</para></listitem>
 257
 258         <listitem><para>Instead of using the
 259         <function>syslog()</function> call to log directly to the
 260         system syslog service, a new-style daemon may choose to simply
 261         log to standard error via <function>fprintf()</function>,
 262         which is then forwarded to syslog by the init system. If log
 263         levels are necessary, these can be encoded by prefixing
 264         individual log lines with strings like
 265         <literal>&lt;4&gt;</literal> (for log level 4 "WARNING" in the
 266         syslog priority scheme), following a similar style as the
 267         Linux kernel's <function>printk()</function> level system. For
 268         details, see
 269         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 270         and
 271         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
 272
 273       </orderedlist>
 274
 275       <para>These recommendations are similar but not identical to the
 276       <ulink
 277       url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple
 278       MacOS X Daemon Requirements</ulink>.</para>
 279     </refsect2>
 280
 281   </refsect1>
 282   <refsect1>
 283     <title>Activation</title>
 284
 285     <para>New-style init systems provide multiple additional
 286     mechanisms to activate services, as detailed below. It is common
 287     that services are configured to be activated via more than one
 288     mechanism at the same time. An example for systemd:
 289     <filename>bluetoothd.service</filename> might get activated either
 290     when Bluetooth hardware is plugged in, or when an application
 291     accesses its programming interfaces via D-Bus. Or, a print server
 292     daemon might get activated when traffic arrives at an IPP port, or
 293     when a printer is plugged in, or when a file is queued in the
 294     printer spool directory. Even for services that are intended to be
 295     started on system bootup unconditionally, it is a good idea to
 296     implement some of the various activation schemes outlined below,
 297     in order to maximize parallelization. If a daemon implements a
 298     D-Bus service or listening socket, implementing the full bus and
 299     socket activation scheme allows starting of the daemon with its
 300     clients in parallel (which speeds up boot-up), since all its
 301     communication channels are established already, and no request is
 302     lost because client requests will be queued by the bus system (in
 303     case of D-Bus) or the kernel (in case of sockets) until the
 304     activation is completed.</para>
 305
 306     <refsect2>
 307       <title>Activation on Boot</title>
 308
 309       <para>Old-style daemons are usually activated exclusively on
 310       boot (and manually by the administrator) via SysV init scripts,
 311       as detailed in the <ulink
 312       url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
 313       Linux Standard Base Core Specification</ulink>. This method of
 314       activation is supported ubiquitously on Linux init systems, both
 315       old-style and new-style systems. Among other issues, SysV init
 316       scripts have the disadvantage of involving shell scripts in the
 317       boot process. New-style init systems generally employ updated
 318       versions of activation, both during boot-up and during runtime
 319       and using more minimal service description files.</para>
 320
 321       <para>In systemd, if the developer or administrator wants to
 322       make sure that a service or other unit is activated
 323       automatically on boot, it is recommended to place a symlink to
 324       the unit file in the <filename>.wants/</filename> directory of
 325       either <filename>multi-user.target</filename> or
 326       <filename>graphical.target</filename>, which are normally used
 327       as boot targets at system startup. See
 328       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 329       for details about the <filename>.wants/</filename> directories,
 330       and
 331       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 332       for details about the two boot targets.</para>
 333
 334     </refsect2>
 335
 336     <refsect2>
 337       <title>Socket-Based Activation</title>
 338
 339       <para>In order to maximize the possible parallelization and
 340       robustness and simplify configuration and development, it is
 341       recommended for all new-style daemons that communicate via
 342       listening sockets to employ socket-based activation. In a
 343       socket-based activation scheme, the creation and binding of the
 344       listening socket as primary communication channel of daemons to
 345       local (and sometimes remote) clients is moved out of the daemon
 346       code and into the init system. Based on per-daemon
 347       configuration, the init system installs the sockets and then
 348       hands them off to the spawned process as soon as the respective
 349       daemon is to be started. Optionally, activation of the service
 350       can be delayed until the first inbound traffic arrives at the
 351       socket to implement on-demand activation of daemons. However,
 352       the primary advantage of this scheme is that all providers and
 353       all consumers of the sockets can be started in parallel as soon
 354       as all sockets are established. In addition to that, daemons can
 355       be restarted with losing only a minimal number of client
 356       transactions, or even any client request at all (the latter is
 357       particularly true for state-less protocols, such as DNS or
 358       syslog), because the socket stays bound and accessible during
 359       the restart, and all requests are queued while the daemon cannot
 360       process them.</para>
 361
 362       <para>New-style daemons which support socket activation must be
 363       able to receive their sockets from the init system instead of
 364       creating and binding them themselves. For details about the
 365       programming interfaces for this scheme provided by systemd, see
 366       <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 367       and
 368       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 369       For details about porting existing daemons to socket-based
 370       activation, see below. With minimal effort, it is possible to
 371       implement socket-based activation in addition to traditional
 372       internal socket creation in the same codebase in order to
 373       support both new-style and old-style init systems from the same
 374       daemon binary.</para>
 375
 376       <para>systemd implements socket-based activation via
 377       <filename>.socket</filename> units, which are described in
 378       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 379       When configuring socket units for socket-based activation, it is
 380       essential that all listening sockets are pulled in by the
 381       special target unit <filename>sockets.target</filename>. It is
 382       recommended to place a
 383       <varname>WantedBy=sockets.target</varname> directive in the
 384       <literal>[Install]</literal> section to automatically add such a
 385       dependency on installation of a socket unit. Unless
 386       <varname>DefaultDependencies=no</varname> is set, the necessary
 387       ordering dependencies are implicitly created for all socket
 388       units. For more information about
 389       <filename>sockets.target</filename>, see
 390       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 391       It is not necessary or recommended to place any additional
 392       dependencies on socket units (for example from
 393       <filename>multi-user.target</filename> or suchlike) when one is
 394       installed in <filename>sockets.target</filename>.</para>
 395     </refsect2>
 396
 397     <refsect2>
 398       <title>Bus-Based Activation</title>
 399
 400       <para>When the D-Bus IPC system is used for communication with
 401       clients, new-style daemons should employ bus activation so that
 402       they are automatically activated when a client application
 403       accesses their IPC interfaces. This is configured in D-Bus
 404       service files (not to be confused with systemd service unit
 405       files!). To ensure that D-Bus uses systemd to start-up and
 406       maintain the daemon, use the <varname>SystemdService=</varname>
 407       directive in these service files to configure the matching
 408       systemd service for a D-Bus service. e.g.: For a D-Bus service
 409       whose D-Bus activation file is named
 410       <filename>org.freedesktop.RealtimeKit.service</filename>, make
 411       sure to set
 412       <varname>SystemdService=rtkit-daemon.service</varname> in that
 413       file to bind it to the systemd service
 414       <filename>rtkit-daemon.service</filename>. This is needed to
 415       make sure that the daemon is started in a race-free fashion when
 416       activated via multiple mechanisms simultaneously.</para>
 417     </refsect2>
 418
 419     <refsect2>
 420       <title>Device-Based Activation</title>
 421
 422       <para>Often, daemons that manage a particular type of hardware
 423       should be activated only when the hardware of the respective
 424       kind is plugged in or otherwise becomes available. In a
 425       new-style init system, it is possible to bind activation to
 426       hardware plug/unplug events. In systemd, kernel devices
 427       appearing in the sysfs/udev device tree can be exposed as units
 428       if they are tagged with the string <literal>systemd</literal>.
 429       Like any other kind of unit, they may then pull in other units
 430       when activated (i.e. plugged in) and thus implement device-based
 431       activation. systemd dependencies may be encoded in the udev
 432       database via the <varname>SYSTEMD_WANTS=</varname> property. See
 433       <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 434       for details. Often, it is nicer to pull in services from devices
 435       only indirectly via dedicated targets. Example: Instead of
 436       pulling in <filename>bluetoothd.service</filename> from all the
 437       various bluetooth dongles and other hardware available, pull in
 438       bluetooth.target from them and
 439       <filename>bluetoothd.service</filename> from that target. This
 440       provides for nicer abstraction and gives administrators the
 441       option to enable <filename>bluetoothd.service</filename> via
 442       controlling a <filename>bluetooth.target.wants/</filename>
 443       symlink uniformly with a command like <command>enable</command>
 444       of
 445       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 446       instead of manipulating the udev ruleset.</para>
 447     </refsect2>
 448
 449     <refsect2>
 450       <title>Path-Based Activation</title>
 451
 452       <para>Often, runtime of daemons processing spool files or
 453       directories (such as a printing system) can be delayed until
 454       these file system objects change state, or become non-empty.
 455       New-style init systems provide a way to bind service activation
 456       to file system changes. systemd implements this scheme via
 457       path-based activation configured in <filename>.path</filename>
 458       units, as outlined in
 459       <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 460     </refsect2>
 461
 462     <refsect2>
 463       <title>Timer-Based Activation</title>
 464
 465       <para>Some daemons that implement clean-up jobs that are
 466       intended to be executed in regular intervals benefit from
 467       timer-based activation. In systemd, this is implemented via
 468       <filename>.timer</filename> units, as described in
 469       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 470     </refsect2>
 471
 472     <refsect2>
 473       <title>Other Forms of Activation</title>
 474
 475       <para>Other forms of activation have been suggested and
 476       implemented in some systems. However, there are often simpler or
 477       better alternatives, or they can be put together of combinations
 478       of the schemes above. Example: Sometimes, it appears useful to
 479       start daemons or <filename>.socket</filename> units when a
 480       specific IP address is configured on a network interface,
 481       because network sockets shall be bound to the address. However,
 482       an alternative to implement this is by utilizing the Linux
 483       <constant>IP_FREEBIND</constant> socket option, as accessible
 484       via <varname>FreeBind=yes</varname> in systemd socket files (see
 485       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 486       for details). This option, when enabled, allows sockets to be
 487       bound to a non-local, not configured IP address, and hence
 488       allows bindings to a particular IP address before it actually
 489       becomes available, making such an explicit dependency to the
 490       configured address redundant. Another often suggested trigger
 491       for service activation is low system load. However, here too, a
 492       more convincing approach might be to make proper use of features
 493       of the operating system, in particular, the CPU or IO scheduler
 494       of Linux. Instead of scheduling jobs from userspace based on
 495       monitoring the OS scheduler, it is advisable to leave the
 496       scheduling of processes to the OS scheduler itself. systemd
 497       provides fine-grained access to the CPU and IO schedulers. If a
 498       process executed by the init system shall not negatively impact
 499       the amount of CPU or IO bandwidth available to other processes,
 500       it should be configured with
 501       <varname>CPUSchedulingPolicy=idle</varname> and/or
 502       <varname>IOSchedulingClass=idle</varname>. Optionally, this may
 503       be combined with timer-based activation to schedule background
 504       jobs during runtime and with minimal impact on the system, and
 505       remove it from the boot phase itself.</para>
 506     </refsect2>
 507
 508   </refsect1>
 509   <refsect1>
 510     <title>Integration with Systemd</title>
 511
 512     <refsect2>
 513       <title>Writing Systemd Unit Files</title>
 514
 515       <para>When writing systemd unit files, it is recommended to
 516       consider the following suggestions:</para>
 517
 518       <orderedlist>
 519         <listitem><para>If possible, do not use the
 520         <varname>Type=forking</varname> setting in service files. But
 521         if you do, make sure to set the PID file path using
 522         <varname>PIDFile=</varname>. See
 523         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 524         for details.</para></listitem>
 525
 526         <listitem><para>If your daemon registers a D-Bus name on the
 527         bus, make sure to use <varname>Type=dbus</varname> in the
 528         service file if possible.</para></listitem>
 529
 530         <listitem><para>Make sure to set a good human-readable
 531         description string with
 532         <varname>Description=</varname>.</para></listitem>
 533
 534         <listitem><para>Do not disable
 535         <varname>DefaultDependencies=</varname>, unless you really
 536         know what you do and your unit is involved in early boot or
 537         late system shutdown.</para></listitem>
 538
 539         <listitem><para>Normally, little if any dependencies should
 540         need to be defined explicitly. However, if you do configure
 541         explicit dependencies, only refer to unit names listed on
 542         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 543         or names introduced by your own package to keep the unit file
 544         operating system-independent.</para></listitem>
 545
 546         <listitem><para>Make sure to include an
 547         <literal>[Install]</literal> section including installation
 548         information for the unit file. See
 549         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 550         for details. To activate your service on boot, make sure to
 551         add a <varname>WantedBy=multi-user.target</varname> or
 552         <varname>WantedBy=graphical.target</varname> directive. To
 553         activate your socket on boot, make sure to add
 554         <varname>WantedBy=sockets.target</varname>. Usually, you also
 555         want to make sure that when your service is installed, your
 556         socket is installed too, hence add
 557         <varname>Also=foo.socket</varname> in your service file
 558         <filename>foo.service</filename>, for a hypothetical program
 559         <filename>foo</filename>.</para></listitem>
 560
 561       </orderedlist>
 562     </refsect2>
 563
 564     <refsect2>
 565       <title>Installing Systemd Service Files</title>
 566
 567       <para>At the build installation time (e.g. <command>make
 568       install</command> during package build), packages are
 569       recommended to install their systemd unit files in the directory
 570       returned by <command>pkg-config systemd
 571       --variable=systemdsystemunitdir</command> (for system services)
 572       or <command>pkg-config systemd
 573       --variable=systemduserunitdir</command> (for user services).
 574       This will make the services available in the system on explicit
 575       request but not activate them automatically during boot.
 576       Optionally, during package installation (e.g. <command>rpm
 577       -i</command> by the administrator), symlinks should be created
 578       in the systemd configuration directories via the
 579       <command>enable</command> command of the
 580       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 581       tool to activate them automatically on boot.</para>
 582
 583       <para>Packages using
 584       <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 585       are recommended to use a configure script
 586       excerpt like the following to determine the
 587       unit installation path during source
 588       configuration:</para>
 589
 590       <programlisting>PKG_PROG_PKG_CONFIG
 591 AC_ARG_WITH([systemdsystemunitdir],
 592      [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],,
 593      [with_systemdsystemunitdir=auto])
 594 AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [
 595      def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)
 596
 597      AS_IF([test "x$def_systemdsystemunitdir" = "x"],
 598    [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"],
 599     [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])])
 600     with_systemdsystemunitdir=no],
 601    [with_systemdsystemunitdir="$def_systemdsystemunitdir"])])
 602 AS_IF([test "x$with_systemdsystemunitdir" != "xno"],
 603       [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])])
 604 AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</programlisting>
 605
 606       <para>This snippet allows automatic
 607       installation of the unit files on systemd
 608       machines, and optionally allows their
 609       installation even on machines lacking
 610       systemd. (Modification of this snippet for the
 611       user unit directory is left as an exercise for the
 612       reader.)</para>
 613
 614       <para>Additionally, to ensure that
 615       <command>make distcheck</command> continues to
 616       work, it is recommended to add the following
 617       to the top-level <filename>Makefile.am</filename>
 618       file in
 619       <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
 620       projects:</para>
 621
 622       <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
 623   --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>
 624
 625       <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
 626
 627       <programlisting>if HAVE_SYSTEMD
 628 systemdsystemunit_DATA = \
 629   foobar.socket \
 630   foobar.service
 631 endif</programlisting>
 632
 633       <para>In the
 634       <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 635       <filename>.spec</filename> file, use snippets like the following
 636       to enable/disable the service during
 637       installation/deinstallation. This makes use of the RPM macros
 638       shipped along systemd. Consult the packaging guidelines of your
 639       distribution for details and the equivalent for other package
 640       managers.</para>
 641
 642       <para>At the top of the file:</para>
 643
 644       <programlisting>BuildRequires: systemd
 645 %{?systemd_requires}</programlisting>
 646
 647       <para>And as scriptlets, further down:</para>
 648
 649       <programlisting>%post
 650 %systemd_post foobar.service foobar.socket
 651
 652 %preun
 653 %systemd_preun foobar.service foobar.socket
 654
 655 %postun
 656 %systemd_postun</programlisting>
 657
 658       <para>If the service shall be restarted during upgrades, replace
 659       the <literal>%postun</literal> scriptlet above with the
 660       following:</para>
 661
 662       <programlisting>%postun
 663 %systemd_postun_with_restart foobar.service</programlisting>
 664
 665       <para>Note that <literal>%systemd_post</literal> and
 666       <literal>%systemd_preun</literal> expect the names of all units
 667       that are installed/removed as arguments, separated by spaces.
 668       <literal>%systemd_postun</literal> expects no arguments.
 669       <literal>%systemd_postun_with_restart</literal> expects the
 670       units to restart as arguments.</para>
 671
 672       <para>To facilitate upgrades from a package version that shipped
 673       only SysV init scripts to a package version that ships both a
 674       SysV init script and a native systemd service file, use a
 675       fragment like the following:</para>
 676
 677       <programlisting>%triggerun -- foobar &lt; 0.47.11-1
 678 if /sbin/chkconfig --level 5 foobar ; then
 679   /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
 680 fi</programlisting>
 681
 682       <para>Where 0.47.11-1 is the first package version that includes
 683       the native unit file. This fragment will ensure that the first
 684       time the unit file is installed, it will be enabled if and only
 685       if the SysV init script is enabled, thus making sure that the
 686       enable status is not changed. Note that
 687       <command>chkconfig</command> is a command specific to Fedora
 688       which can be used to check whether a SysV init script is
 689       enabled. Other operating systems will have to use different
 690       commands here.</para>
 691     </refsect2>
 692   </refsect1>
 693
 694   <refsect1>
 695     <title>Porting Existing Daemons</title>
 696
 697     <para>Since new-style init systems such as systemd are compatible
 698     with traditional SysV init systems, it is not strictly necessary
 699     to port existing daemons to the new style. However, doing so
 700     offers additional functionality to the daemons as well as
 701     simplifying integration into new-style init systems.</para>
 702
 703     <para>To port an existing SysV compatible daemon, the following
 704     steps are recommended:</para>
 705
 706     <orderedlist>
 707       <listitem><para>If not already implemented, add an optional
 708       command line switch to the daemon to disable daemonization. This
 709       is useful not only for using the daemon in new-style init
 710       systems, but also to ease debugging.</para></listitem>
 711
 712       <listitem><para>If the daemon offers interfaces to other
 713       software running on the local system via local
 714       <constant>AF_UNIX</constant> sockets, consider implementing
 715       socket-based activation (see above). Usually, a minimal patch is
 716       sufficient to implement this: Extend the socket creation in the
 717       daemon code so that
 718       <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 719       is checked for already passed sockets first. If sockets are
 720       passed (i.e. when <function>sd_listen_fds()</function> returns a
 721       positive value), skip the socket creation step and use the
 722       passed sockets. Secondly, ensure that the file system socket
 723       nodes for local <constant>AF_UNIX</constant> sockets used in the
 724       socket-based activation are not removed when the daemon shuts
 725       down, if sockets have been passed. Third, if the daemon normally
 726       closes all remaining open file descriptors as part of its
 727       initialization, the sockets passed from the init system must be
 728       spared. Since new-style init systems guarantee that no left-over
 729       file descriptors are passed to executed processes, it might be a
 730       good choice to simply skip the closing of all remaining open
 731       file descriptors if sockets are passed.</para></listitem>
 732
 733       <listitem><para>Write and install a systemd unit file for the
 734       service (and the sockets if socket-based activation is used, as
 735       well as a path unit file, if the daemon processes a spool
 736       directory), see above for details.</para></listitem>
 737
 738       <listitem><para>If the daemon exposes interfaces via D-Bus,
 739       write and install a D-Bus activation file for the service, see
 740       above for details.</para></listitem>
 741     </orderedlist>
 742   </refsect1>
 743
 744   <refsect1>
 745     <title>Placing Daemon Data</title>
 746
 747     <para>It is recommended to follow the general guidelines for
 748     placing package files, as discussed in
 749     <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 750   </refsect1>
 751
 752   <refsect1>
 753     <title>See Also</title>
 754     <para>
 755       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 756       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 757       <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 758       <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 759       <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 760       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 761       <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 762     </para>
 763   </refsect1>
 764
 765 </refentry>