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