daemon.xml 52.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="daemon">

        <refentryinfo>
                <title>daemon</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>daemon</refentrytitle>
                <manvolnum>7</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>daemon</refname>
                <refpurpose>Writing and packaging system daemons</refpurpose>
        </refnamediv>

        <refsect1>
                <title>Description</title>

                <para>A daemon is a service process that runs in the
                background and supervises the system or provides
                functionality to other processes. Traditionally,
                daemons are implemented following a scheme originating
                in SysV Unix. Modern daemons should follow a simpler
                yet more powerful scheme (here called "new-style"
                daemons), as implemented by
                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
                manual page covers both schemes, and in
                particular includes recommendations for daemons that
                shall be included in the systemd init system.</para>

                <refsect2>
                        <title>SysV Daemons</title>

                        <para>When a traditional SysV daemon
                        starts, it should execute the following steps
                        as part of the initialization. Note that these
                        steps are unnecessary for new-style daemons (see below),
                        and should only be implemented if compatibility
                        with SysV is essential.</para>

                        <orderedlist>
                                <listitem><para>Close all open file
77 78
                                descriptors except standard input, output,
                                and error (i.e. the first three file
79 80 81
                                descriptors 0, 1, 2). This ensures
                                that no accidentally passed file
                                descriptor stays around in the daemon
82
                                process. On Linux, this is best
83 84 85 86 87 88 89 90 91 92 93 94
                                implemented by iterating through
                                <filename>/proc/self/fd</filename>,
                                with a fallback of iterating from file
                                descriptor 3 to the value returned by
                                <function>getrlimit()</function> for
                                RLIMIT_NOFILE.</para></listitem>

                                <listitem><para>Reset all signal
                                handlers to their default. This is
                                best done by iterating through the
                                available signals up to the limit of
                                _NSIG and resetting them to
95
                                <constant>SIG_DFL</constant>.</para></listitem>
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117

                                <listitem><para>Reset the signal mask
                                using
                                <function>sigprocmask()</function>.</para></listitem>

                                <listitem><para>Sanitize the
                                environment block, removing or
                                resetting environment variables that
                                might negatively impact daemon
                                runtime.</para></listitem>

                                <listitem><para>Call <function>fork()</function>,
                                to create a background
                                process.</para></listitem>

                                <listitem><para>In the child, call
                                <function>setsid()</function> to
                                detach from any terminal and create an
                                independent session.</para></listitem>

                                <listitem><para>In the child, call
                                <function>fork()</function> again, to
118
                                ensure that the daemon can never re-acquire
119 120 121 122 123 124 125 126 127 128 129 130
                                a terminal again.</para></listitem>

                                <listitem><para>Call <function>exit()</function> in the
                                first child, so that only the second
                                child (the actual daemon process)
                                stays around. This ensures that the
                                daemon process is re-parented to
                                init/PID 1, as all daemons should
                                be.</para></listitem>

                                <listitem><para>In the daemon process,
                                connect <filename>/dev/null</filename>
131 132
                                to standard input, output, and error.
                                </para></listitem>
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151

                                <listitem><para>In the daemon process,
                                reset the umask to 0, so that the file
                                modes passed to <function>open()</function>, <function>mkdir()</function> and
                                suchlike directly control the access
                                mode of the created files and
                                directories.</para></listitem>

                                <listitem><para>In the daemon process,
                                change the current directory to the
                                root directory (/), in order to avoid
                                that the daemon involuntarily
                                blocks mount points from being
                                unmounted.</para></listitem>

                                <listitem><para>In the daemon process,
                                write the daemon PID (as returned by
                                <function>getpid()</function>) to a
                                PID file, for example
152
                                <filename>/run/foobar.pid</filename>
153
                                (for a hypothetical daemon "foobar")
154 155 156 157
                                to ensure that the daemon cannot be
                                started more than once. This must be
                                implemented in race-free fashion so
                                that the PID file is only updated when
158
                                it is verified at the same time that
159 160
                                the PID previously stored in the PID
                                file no longer exists or belongs to a
161
                                foreign process.</para></listitem>
162 163 164 165 166 167

                                <listitem><para>In the daemon process,
                                drop privileges, if possible and
                                applicable.</para></listitem>

                                <listitem><para>From the daemon
168
                                process, notify the original process
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
                                started that initialization is
                                complete. This can be implemented via
                                an unnamed pipe or similar
                                communication channel that is created
                                before the first
                                <function>fork()</function> and hence
                                available in both the original and the
                                daemon process.</para></listitem>

                                <listitem><para>Call
                                <function>exit()</function> in the
                                original process. The process that
                                invoked the daemon must be able to
                                rely on that this
                                <function>exit()</function> happens
                                after initialization is complete and
                                all external communication channels
                                are established and
                                accessible.</para></listitem>
                        </orderedlist>

                        <para>The BSD <function>daemon()</function> function should not be
                        used, as it implements only a subset of these steps.</para>

                        <para>A daemon that needs to provide
                        compatibility with SysV systems should
                        implement the scheme pointed out
                        above. However, it is recommended to make this
                        behavior optional and configurable via a
198
                        command line argument to ease debugging as
199 200 201 202 203 204 205 206 207 208 209 210 211
                        well as to simplify integration into systems
                        using systemd.</para>
                </refsect2>

                <refsect2>
                        <title>New-Style Daemons</title>

                        <para>Modern services for Linux should be
                        implemented as new-style daemons. This makes it
                        easier to supervise and control them at
                        runtime and simplifies their
                        implementation.</para>

212
                        <para>For developing a new-style daemon, none
213 214 215 216 217 218
                        of the initialization steps recommended for
                        SysV daemons need to be implemented. New-style
                        init systems such as systemd make all of them
                        redundant. Moreover, since some of these steps
                        interfere with process monitoring, file
                        descriptor passing and other functionality of
219
                        the init system, it is recommended not to
220 221 222 223
                        execute them when run as new-style
                        service.</para>

                        <para>Note that new-style init systems
224 225
                        guarantee execution of daemon processes in a
                        clean process context: it is guaranteed that
226 227 228
                        the environment block is sanitized, that the
                        signal handlers and mask is reset and that no
                        left-over file descriptors are passed. Daemons
229 230
                        will be executed in their own session, with
                        standard input/output/error connected to
231
                        <filename>/dev/null</filename> unless
232 233
                        otherwise configured. The umask is reset.
                        </para>
234 235 236 237 238

                        <para>It is recommended for new-style daemons
                        to implement the following:</para>

                        <orderedlist>
239
                                <listitem><para>If <constant>SIGTERM</constant> is
240 241 242
                                received, shut down the daemon and
                                exit cleanly.</para></listitem>

243
                                <listitem><para>If <constant>SIGHUP</constant> is received,
244 245 246 247 248 249 250 251 252
                                reload the configuration files, if
                                this applies.</para></listitem>

                                <listitem><para>Provide a correct exit
                                code from the main daemon process, as
                                this is used by the init system to
                                detect service errors and problems. It
                                is recommended to follow the exit code
                                scheme as defined in the <ulink
253
                                url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
254 255 256 257
                                recommendations for SysV init
                                scripts</ulink>.</para></listitem>

                                <listitem><para>If possible and
258
                                applicable, expose the daemon's control
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275
                                interface via the D-Bus IPC system and
                                grab a bus name as last step of
                                initialization.</para></listitem>

                                <listitem><para>For integration in
                                systemd, provide a
                                <filename>.service</filename> unit
                                file that carries information about
                                starting, stopping and otherwise
                                maintaining the daemon. See
                                <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for details.</para></listitem>

                                <listitem><para>As much as possible,
                                rely on the init system's
                                functionality to limit the access of
                                the daemon to files, services and
276
                                other resources, i.e. in the case of
277 278 279 280 281 282 283 284 285 286
                                systemd, rely on systemd's resource
                                limit control instead of implementing
                                your own, rely on systemd's privilege
                                dropping code instead of implementing
                                it in the daemon, and similar. See
                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for the available
                                controls.</para></listitem>

                                <listitem><para>If D-Bus is used, make
287
                                your daemon bus-activatable by
288 289 290 291 292 293 294
                                supplying a D-Bus service activation
                                configuration file. This has multiple
                                advantages: your daemon may be started
                                lazily on-demand; it may be started in
                                parallel to other daemons requiring it
                                -- which maximizes parallelization and
                                boot-up speed; your daemon can be
295
                                restarted on failure without losing
296 297 298 299 300 301 302 303 304 305
                                any bus requests, as the bus queues
                                requests for activatable services. See
                                below for details.</para></listitem>

                                <listitem><para>If your daemon
                                provides services to other local
                                processes or remote clients via a
                                socket, it should be made
                                socket-activatable following the
                                scheme pointed out below. Like D-Bus
306
                                activation, this enables on-demand
307 308 309
                                starting of services as well as it
                                allows improved parallelization of
                                service start-up. Also, for state-less
310
                                protocols (such as syslog, DNS), a
311 312 313 314 315
                                daemon implementing socket-based
                                activation can be restarted without
                                losing a single request. See below for
                                details.</para></listitem>

316
                                <listitem><para>If applicable, a daemon
317 318 319 320 321 322 323
                                should notify the init system about
                                startup completion or status updates
                                via the
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                interface.</para></listitem>

                                <listitem><para>Instead of using the
324 325 326 327 328 329 330 331 332 333 334 335 336 337 338
                                <function>syslog()</function> call to
                                log directly to the system syslog
                                service, a new-style daemon may choose
                                to simply log to standard error via
                                <function>fprintf()</function>, which
                                is then forwarded to syslog by the
                                init system. If log priorities are
                                necessary, these can be encoded by
                                prefixing individual log lines with
                                strings like "&lt;4&gt;" (for log
                                priority 4 "WARNING" in the syslog
                                priority scheme), following a similar
                                style as the Linux kernel's
                                <function>printk()</function> priority
                                system. For details, see
339 340 341 342 343 344 345 346
                                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                and
                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>

                        </orderedlist>

                        <para>These recommendations are similar but
                        not identical to the <ulink
347
                        url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple
348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367
                        MacOS X Daemon Requirements</ulink>.</para>
                </refsect2>

        </refsect1>
        <refsect1>
                <title>Activation</title>

                <para>New-style init systems provide multiple
                additional mechanisms to activate services, as
                detailed below. It is common that services are
                configured to be activated via more than one mechanism
                at the same time. An example for systemd:
                <filename>bluetoothd.service</filename> might get
                activated either when Bluetooth hardware is plugged
                in, or when an application accesses its programming
                interfaces via D-Bus. Or, a print server daemon might
                get activated when traffic arrives at an IPP port, or
                when a printer is plugged in, or when a file is queued
                in the printer spool directory. Even for services that
                are intended to be started on system bootup
368
                unconditionally, it is a good idea to implement some of
369
                the various activation schemes outlined below, in
370
                order to maximize parallelization. If a daemon
371 372 373 374 375 376 377
                implements a D-Bus service or listening socket,
                implementing the full bus and socket activation scheme
                allows starting of the daemon with its clients in
                parallel (which speeds up boot-up), since all its
                communication channels are established already, and no
                request is lost because client requests will be queued
                by the bus system (in case of D-Bus) or the kernel (in
378
                case of sockets) until the activation is
379 380 381 382 383 384 385 386 387
                completed.</para>

                <refsect2>
                        <title>Activation on Boot</title>

                        <para>Old-style daemons are usually activated
                        exclusively on boot (and manually by the
                        administrator) via SysV init scripts, as
                        detailed in the <ulink
388
                        url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
389 390 391 392
                        Linux Standard Base Core
                        Specification</ulink>. This method of
                        activation is supported ubiquitously on Linux
                        init systems, both old-style and new-style
393
                        systems. Among other issues, SysV init scripts
394 395 396 397 398 399 400 401
                        have the disadvantage of involving shell
                        scripts in the boot process. New-style init
                        systems generally employ updated versions of
                        activation, both during boot-up and during
                        runtime and using more minimal service
                        description files.</para>

                        <para>In systemd, if the developer or
402
                        administrator wants to make sure that a service or
403
                        other unit is activated automatically on boot,
404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427
                        it is recommended to place a symlink to the
                        unit file in the <filename>.wants/</filename>
                        directory of either
                        <filename>multi-user.target</filename> or
                        <filename>graphical.target</filename>, which
                        are normally used as boot targets at system
                        startup. See
                        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                        for details about the
                        <filename>.wants/</filename> directories, and
                        <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                        for details about the two boot targets.</para>

                </refsect2>

                <refsect2>
                        <title>Socket-Based Activation</title>

                        <para>In order to maximize the possible
                        parallelization and robustness and simplify
                        configuration and development, it is
                        recommended for all new-style daemons that
                        communicate via listening sockets to employ
                        socket-based activation. In a socket-based
428
                        activation scheme, the creation and binding of
429 430 431 432
                        the listening socket as primary communication
                        channel of daemons to local (and sometimes
                        remote) clients is moved out of the daemon
                        code and into the init system. Based on
433
                        per-daemon configuration, the init system
434 435 436
                        installs the sockets and then hands them off
                        to the spawned process as soon as the
                        respective daemon is to be started.
437
                        Optionally, activation of the service can be
438
                        delayed until the first inbound traffic
439
                        arrives at the socket to implement on-demand
440 441 442 443
                        activation of daemons. However, the primary
                        advantage of this scheme is that all providers
                        and all consumers of the sockets can be
                        started in parallel as soon as all sockets
444
                        are established. In addition to that, daemons
445
                        can be restarted with losing only a minimal
446
                        number of client transactions, or even any
447 448 449 450 451 452 453 454 455
                        client request at all (the latter is
                        particularly true for state-less protocols,
                        such as DNS or syslog), because the socket
                        stays bound and accessible during the restart,
                        and all requests are queued while the daemon
                        cannot process them.</para>

                        <para>New-style daemons which support socket
                        activation must be able to receive their
456
                        sockets from the init system instead of
457 458
                        creating and binding them themselves. For
                        details about the programming interfaces for
459
                        this scheme provided by systemd, see
460 461 462 463
                        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                        and
                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. For
                        details about porting existing daemons to
464 465
                        socket-based activation, see below. With
                        minimal effort, it is possible to implement
466 467 468 469 470 471 472 473 474 475 476
                        socket-based activation in addition to
                        traditional internal socket creation in the
                        same codebase in order to support both
                        new-style and old-style init systems from the
                        same daemon binary.</para>

                        <para>systemd implements socket-based
                        activation via <filename>.socket</filename>
                        units, which are described in
                        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. When
                        configuring socket units for socket-based
477
                        activation, it is essential that all listening
478 479 480 481 482
                        sockets are pulled in by the special target
                        unit <filename>sockets.target</filename>. It
                        is recommended to place a
                        <varname>WantedBy=sockets.target</varname>
                        directive in the <literal>[Install]</literal>
483
                        section to automatically add such a
484 485 486
                        dependency on installation of a socket
                        unit. Unless
                        <varname>DefaultDependencies=no</varname> is
487
                        set, the necessary ordering dependencies are
488 489
                        implicitly created for all socket units. For
                        more information about
490
                        <filename>sockets.target</filename>, see
491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511
                        <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. It
                        is not necessary or recommended to place any
                        additional dependencies on socket units (for
                        example from
                        <filename>multi-user.target</filename> or
                        suchlike) when one is installed in
                        <filename>sockets.target</filename>.</para>
                </refsect2>

                <refsect2>
                        <title>Bus-Based Activation</title>

                        <para>When the D-Bus IPC system is used for
                        communication with clients, new-style daemons
                        should employ bus activation so that they are
                        automatically activated when a client
                        application accesses their IPC
                        interfaces. This is configured in D-Bus
                        service files (not to be confused with systemd
                        service unit files!). To ensure that D-Bus
                        uses systemd to start-up and maintain the
512
                        daemon, use the
513
                        <varname>SystemdService=</varname> directive
514
                        in these service files to configure the
515
                        matching systemd service for a D-Bus
516
                        service. e.g.: For a D-Bus service whose D-Bus
517 518 519 520
                        activation file is named
                        <filename>org.freedesktop.RealtimeKit.service</filename>,
                        make sure to set
                        <varname>SystemdService=rtkit-daemon.service</varname>
521
                        in that file to bind it to the systemd
522 523 524 525 526 527 528 529 530 531 532 533 534 535
                        service
                        <filename>rtkit-daemon.service</filename>. This
                        is needed to make sure that the daemon is
                        started in a race-free fashion when activated
                        via multiple mechanisms simultaneously.</para>
                </refsect2>

                <refsect2>
                        <title>Device-Based Activation</title>

                        <para>Often, daemons that manage a particular
                        type of hardware should be activated only when
                        the hardware of the respective kind is plugged
                        in or otherwise becomes available. In a
536
                        new-style init system, it is possible to bind
537 538 539 540
                        activation to hardware plug/unplug events. In
                        systemd, kernel devices appearing in the
                        sysfs/udev device tree can be exposed as units
                        if they are tagged with the string
541 542 543 544
                        <literal>systemd</literal>. Like any other
                        kind of unit, they may then pull in other units
                        when activated (i.e. plugged in) and thus
                        implement device-based activation. systemd
545 546 547 548 549
                        dependencies may be encoded in the udev
                        database via the
                        <varname>SYSTEMD_WANTS=</varname>
                        property. See
                        <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
550
                        for details. Often, it is nicer to pull in
551
                        services from devices only indirectly via
552
                        dedicated targets. Example: Instead of pulling
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603
                        in <filename>bluetoothd.service</filename>
                        from all the various bluetooth dongles and
                        other hardware available, pull in
                        bluetooth.target from them and
                        <filename>bluetoothd.service</filename> from
                        that target. This provides for nicer
                        abstraction and gives administrators the
                        option to enable
                        <filename>bluetoothd.service</filename> via
                        controlling a
                        <filename>bluetooth.target.wants/</filename>
                        symlink uniformly with a command like
                        <command>enable</command> of
                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                        instead of manipulating the udev
                        ruleset.</para>
                </refsect2>

                <refsect2>
                        <title>Path-Based Activation</title>

                        <para>Often, runtime of daemons processing
                        spool files or directories (such as a printing
                        system) can be delayed until these file system
                        objects change state, or become
                        non-empty. New-style init systems provide a
                        way to bind service activation to file system
                        changes. systemd implements this scheme via
                        path-based activation configured in
                        <filename>.path</filename> units, as outlined
                        in
                        <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
                </refsect2>

                <refsect2>
                        <title>Timer-Based Activation</title>

                        <para>Some daemons that implement clean-up
                        jobs that are intended to be executed in
                        regular intervals benefit from timer-based
                        activation. In systemd, this is implemented
                        via <filename>.timer</filename> units, as
                        described in
                        <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
                </refsect2>

                <refsect2>
                        <title>Other Forms of Activation</title>

                        <para>Other forms of activation have been
                        suggested and implemented in some
604
                        systems. However, there are often simpler or
605 606
                        better alternatives, or they can be put
                        together of combinations of the schemes
607
                        above. Example: Sometimes, it appears useful to
608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627
                        start daemons or <filename>.socket</filename>
                        units when a specific IP address is configured
                        on a network interface, because network
                        sockets shall be bound to the
                        address. However, an alternative to implement
                        this is by utilizing the Linux IP_FREEBIND
                        socket option, as accessible via
                        <varname>FreeBind=yes</varname> in systemd
                        socket files (see
                        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                        for details). This option, when enabled,
                        allows sockets to be bound to a non-local, not
                        configured IP address, and hence allows
                        bindings to a particular IP address before it
                        actually becomes available, making such an
                        explicit dependency to the configured address
                        redundant. Another often suggested trigger for
                        service activation is low system
                        load. However, here too, a more convincing
                        approach might be to make proper use of
628
                        features of the operating system, in
629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661
                        particular, the CPU or IO scheduler of
                        Linux. Instead of scheduling jobs from
                        userspace based on monitoring the OS
                        scheduler, it is advisable to leave the
                        scheduling of processes to the OS scheduler
                        itself. systemd provides fine-grained access
                        to the CPU and IO schedulers. If a process
                        executed by the init system shall not
                        negatively impact the amount of CPU or IO
                        bandwidth available to other processes, it
                        should be configured with
                        <varname>CPUSchedulingPolicy=idle</varname>
                        and/or
                        <varname>IOSchedulingClass=idle</varname>. Optionally,
                        this may be combined with timer-based
                        activation to schedule background jobs during
                        runtime and with minimal impact on the system,
                        and remove it from the boot phase
                        itself.</para>
                </refsect2>

        </refsect1>
        <refsect1>
                <title>Integration with Systemd</title>

                <refsect2>
                        <title>Writing Systemd Unit Files</title>

                        <para>When writing systemd unit files, it is
                        recommended to consider the following
                        suggestions:</para>

                        <orderedlist>
662
                                <listitem><para>If possible, do not use
663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704
                                the <varname>Type=forking</varname>
                                setting in service files. But if you
                                do, make sure to set the PID file path
                                using <varname>PIDFile=</varname>. See
                                <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for details.</para></listitem>

                                <listitem><para>If your daemon
                                registers a D-Bus name on the bus,
                                make sure to use
                                <varname>Type=dbus</varname> in the
                                service file if
                                possible.</para></listitem>

                                <listitem><para>Make sure to set a
                                good human-readable description string
                                with
                                <varname>Description=</varname>.</para></listitem>

                                <listitem><para>Do not disable
                                <varname>DefaultDependencies=</varname>,
                                unless you really know what you do and
                                your unit is involved in early boot or
                                late system shutdown.</para></listitem>

                                <listitem><para>Normally, little if
                                any dependencies should need to
                                be defined explicitly. However, if you
                                do configure explicit dependencies, only refer to
                                unit names listed on
                                <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                or names introduced by your own
                                package to keep the unit file
                                operating
                                system-independent.</para></listitem>

                                <listitem><para>Make sure to include
                                an <literal>[Install]</literal>
                                section including installation
                                information for the unit file. See
                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for details. To activate your service
705
                                on boot, make sure to add a
706 707 708 709 710
                                <varname>WantedBy=multi-user.target</varname>
                                or
                                <varname>WantedBy=graphical.target</varname>
                                directive. To activate your socket on
                                boot, make sure to add
711
                                <varname>WantedBy=sockets.target</varname>. Usually,
712
                                you also want to make sure that when
713
                                your service is installed, your socket
714 715 716 717 718 719 720 721 722 723 724 725 726 727 728
                                is installed too, hence add
                                <varname>Also=foo.socket</varname> in
                                your service file
                                <filename>foo.service</filename>, for
                                a hypothetical program
                                <filename>foo</filename>.</para></listitem>

                        </orderedlist>
                </refsect2>

                <refsect2>
                        <title>Installing Systemd Service Files</title>

                        <para>At the build installation time
                        (e.g. <command>make install</command> during
729
                        package build), packages are recommended to
730 731 732 733 734 735 736 737 738 739 740 741
                        install their systemd unit files in the
                        directory returned by <command>pkg-config
                        systemd
                        --variable=systemdsystemunitdir</command> (for
                        system services) or <command>pkg-config
                        systemd
                        --variable=systemduserunitdir</command>
                        (for user services). This will make the
                        services available in the system on explicit
                        request but not activate them automatically
                        during boot. Optionally, during package
                        installation (e.g. <command>rpm -i</command>
742
                        by the administrator), symlinks should be
743 744 745 746
                        created in the systemd configuration
                        directories via the <command>enable</command>
                        command of the
                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
747
                        tool to activate them automatically on
748 749 750 751 752 753 754 755 756 757 758
                        boot.</para>

                        <para>Packages using
                        <citerefentry><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                        are recommended to use a configure script
                        excerpt like the following to determine the
                        unit installation path during source
                        configuration:</para>

                        <programlisting>PKG_PROG_PKG_CONFIG
AC_ARG_WITH([systemdsystemunitdir],
759 760 761 762 763 764 765 766 767 768 769 770 771
     [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],,
     [with_systemdsystemunitdir=auto])
AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [
     def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)

     AS_IF([test "x$def_systemdsystemunitdir" = "x"],
         [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"],
                [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])])
          with_systemdsystemunitdir=no],
         [with_systemdsystemunitdir="$def_systemdsystemunitdir"])])
AS_IF([test "x$with_systemdsystemunitdir" != "xno"],
      [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])])
AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</programlisting>
772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801

                        <para>This snippet allows automatic
                        installation of the unit files on systemd
                        machines, and optionally allows their
                        installation even on machines lacking
                        systemd. (Modification of this snippet for the
                        user unit directory is left as an exercise for the
                        reader.)</para>

                        <para>Additionally, to ensure that
                        <command>make distcheck</command> continues to
                        work, it is recommended to add the following
                        to the top-level <filename>Makefile.am</filename>
                        file in
                        <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
                        projects:</para>

                        <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
        --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>

                        <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>

                        <programlisting>if HAVE_SYSTEMD
systemdsystemunit_DATA = \
        foobar.socket \
        foobar.service
endif</programlisting>

                        <para>In the
                        <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
802
                        <filename>.spec</filename> file, use snippets
803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827
                        like the following to enable/disable the
                        service during
                        installation/deinstallation. This makes use of
                        the RPM macros shipped along systemd. Consult
                        the packaging guidelines of your distribution
                        for details and the equivalent for other
                        package managers.</para>

                        <para>At the top of the file:</para>

                        <programlisting>BuildRequires: systemd
%{?systemd_requires}</programlisting>

                        <para>And as scriptlets, further down:</para>

                        <programlisting>%post
%systemd_post foobar.service foobar.socket

%preun
%systemd_preun foobar.service foobar.socket

%postun
%systemd_postun</programlisting>

                        <para>If the service shall be restarted during
828
                        upgrades, replace the
829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859
                        <literal>%postun</literal> scriptlet above
                        with the following:</para>

                        <programlisting>%postun
%systemd_postun_with_restart foobar.service</programlisting>

                        <para>Note that
                        <literal>%systemd_post</literal> and
                        <literal>%systemd_preun</literal> expect the
                        names of all units that are installed/removed
                        as arguments, separated by
                        spaces. <literal>%systemd_postun</literal>
                        expects no
                        arguments. <literal>%systemd_postun_with_restart</literal>
                        expects the units to restart as
                        arguments.</para>

                        <para>To facilitate upgrades from a package
                        version that shipped only SysV init scripts to
                        a package version that ships both a SysV init
                        script and a native systemd service file, use
                        a fragment like the following:</para>

                        <programlisting>%triggerun -- foobar &lt; 0.47.11-1
if /sbin/chkconfig --level 5 foobar ; then
        /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
fi</programlisting>

                        <para>Where 0.47.11-1 is the first package
                        version that includes the native unit
                        file. This fragment will ensure that the first
860
                        time the unit file is installed, it will be
861 862 863 864 865 866 867 868 869 870 871 872 873 874 875
                        enabled if and only if the SysV init script is
                        enabled, thus making sure that the enable
                        status is not changed. Note that
                        <command>chkconfig</command> is a command
                        specific to Fedora which can be used to check
                        whether a SysV init script is enabled. Other
                        operating systems will have to use different
                        commands here.</para>
                </refsect2>
        </refsect1>

        <refsect1>
                <title>Porting Existing Daemons</title>

                <para>Since new-style init systems such as systemd are
876
                compatible with traditional SysV init systems, it is
877
                not strictly necessary to port existing daemons to the
878
                new style. However, doing so offers additional
879 880 881
                functionality to the daemons as well as simplifying
                integration into new-style init systems.</para>

882
                <para>To port an existing SysV compatible daemon, the
883 884 885 886 887 888 889 890 891 892 893 894
                following steps are recommended:</para>

                <orderedlist>
                        <listitem><para>If not already implemented,
                        add an optional command line switch to the
                        daemon to disable daemonization. This is
                        useful not only for using the daemon in
                        new-style init systems, but also to ease
                        debugging.</para></listitem>

                        <listitem><para>If the daemon offers
                        interfaces to other software running on the
895
                        local system via local <constant>AF_UNIX</constant> sockets,
896
                        consider implementing socket-based activation
897
                        (see above). Usually, a minimal patch is
898 899 900 901 902 903 904 905
                        sufficient to implement this: Extend the
                        socket creation in the daemon code so that
                        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                        is checked for already passed sockets
                        first. If sockets are passed (i.e. when
                        <function>sd_listen_fds()</function> returns a
                        positive value), skip the socket creation step
                        and use the passed sockets. Secondly, ensure
906 907
                        that the file system socket nodes for local
                        <constant>AF_UNIX</constant> sockets used in the socket-based
908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934
                        activation are not removed when the daemon
                        shuts down, if sockets have been
                        passed. Third, if the daemon normally closes
                        all remaining open file descriptors as part of
                        its initialization, the sockets passed from
                        the init system must be spared. Since
                        new-style init systems guarantee that no
                        left-over file descriptors are passed to
                        executed processes, it might be a good choice
                        to simply skip the closing of all remaining
                        open file descriptors if sockets are
                        passed.</para></listitem>

                        <listitem><para>Write and install a systemd
                        unit file for the service (and the sockets if
                        socket-based activation is used, as well as a
                        path unit file, if the daemon processes a
                        spool directory), see above for
                        details.</para></listitem>

                        <listitem><para>If the daemon exposes
                        interfaces via D-Bus, write and install a
                        D-Bus activation file for the service, see
                        above for details.</para></listitem>
                </orderedlist>
        </refsect1>

935 936 937 938 939 940 941 942
        <refsect1>
                <title>Placing Daemon Data</title>

                <para>It is recommended to follow the general
                guidelines for placing package files, as discussed in
                <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
        </refsect1>

943 944 945 946 947 948 949 950
        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
951 952
                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
953 954 955 956
                </para>
        </refsect1>

</refentry>