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