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