summaryrefslogtreecommitdiff
path: root/man/daemon.xml
blob: 26ba60052158030aded0f05eaffa7220b712d80e (plain)
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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
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
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
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
662
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
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
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
802
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
828
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
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
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
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
<?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
                                descriptors except stdin, stdout,
                                stderr (i.e. the first three file
                                descriptors 0, 1, 2). This ensures
                                that no accidentally passed file
                                descriptor stays around in the daemon
                                process. On Linux, this is best
                                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
                                <constant>SIG_DFL</constant>.</para></listitem>

                                <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
                                ensure that the daemon can never re-acquire
                                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>
                                to standard input, output, and error.
                                </para></listitem>

                                <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
                                <filename>/var/run/foobar.pid</filename>
                                (for a hypothetical daemon "foobar")
                                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
                                it is verified at the same time that
                                the PID previously stored in the PID
                                file no longer exists or belongs to a
                                foreign process. Commonly, some kind of
                                file locking is employed to implement
                                this logic.</para></listitem>

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

                                <listitem><para>From the daemon
                                process, notify the original process
                                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
                        command line argument to ease debugging as
                        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>

                        <para>For developing a new-style daemon, none
                        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
                        the init system, it is recommended not to
                        execute them when run as new-style
                        service.</para>

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

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

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

                                <listitem><para>If <constant>SIGHUP</constant> is received,
                                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
                                url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
                                recommendations for SysV init
                                scripts</ulink>.</para></listitem>

                                <listitem><para>If possible and
                                applicable, expose the daemon's control
                                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
                                other resources, i.e. in the case of
                                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
                                your daemon bus-activatable by
                                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
                                restarted on failure without losing
                                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
                                activation, this enables on-demand
                                starting of services as well as it
                                allows improved parallelization of
                                service start-up. Also, for state-less
                                protocols (such as syslog, DNS), a
                                daemon implementing socket-based
                                activation can be restarted without
                                losing a single request. See below for
                                details.</para></listitem>

                                <listitem><para>If applicable, a daemon
                                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
                                <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. In fact,
                                using this style of logging also
                                enables the init system to optionally
                                direct all application logging to the
                                kernel log buffer (kmsg), as
                                accessible via
                                <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
                                kind of logging may be enabled by
                                setting
                                <varname>StandardError=syslog</varname>
                                in the service unit file. For details,
                                see
                                <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
                        url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">Apple
                        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
                unconditionally, it is a good idea to implement some of
                the various activation schemes outlined below, in
                order to maximize parallelization. If a daemon
                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
                case of sockets) until the activation is
                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
                        url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
                        Linux Standard Base Core
                        Specification</ulink>. This method of
                        activation is supported ubiquitously on Linux
                        init systems, both old-style and new-style
                        systems. Among other issues, SysV init scripts
                        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
                        administrator wants to make sure that a service or
                        other unit is activated automatically on boot,
                        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
                        activation scheme, the creation and binding of
                        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
                        per-daemon configuration, the init system
                        installs the sockets and then hands them off
                        to the spawned process as soon as the
                        respective daemon is to be started.
                        Optionally, activation of the service can be
                        delayed until the first inbound traffic
                        arrives at the socket to implement on-demand
                        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
                        are established. In addition to that, daemons
                        can be restarted with losing only a minimal
                        number of client transactions, or even any
                        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
                        sockets from the init system instead of
                        creating and binding them themselves. For
                        details about the programming interfaces for
                        this scheme provided by systemd, see
                        <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
                        socket-based activation, see below. With
                        minimal effort, it is possible to implement
                        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
                        activation, it is essential that all listening
                        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>
                        section to automatically add such a
                        dependency on installation of a socket
                        unit. Unless
                        <varname>DefaultDependencies=no</varname> is
                        set, the necessary ordering dependencies are
                        implicitly created for all socket units. For
                        more information about
                        <filename>sockets.target</filename>, see
                        <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
                        daemon, use the
                        <varname>SystemdService=</varname> directive
                        in these service files to configure the
                        matching systemd service for a D-Bus
                        service. e.g.: For a D-Bus service whose D-Bus
                        activation file is named
                        <filename>org.freedesktop.RealtimeKit.service</filename>,
                        make sure to set
                        <varname>SystemdService=rtkit-daemon.service</varname>
                        in that file to bind it to the systemd
                        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
                        new-style init system, it is possible to bind
                        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
                        <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
                        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>
                        for details. Often, it is nicer to pull in
                        services from devices only indirectly via
                        dedicated targets. Example: Instead of pulling
                        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
                        systems. However, there are often simpler or
                        better alternatives, or they can be put
                        together of combinations of the schemes
                        above. Example: Sometimes, it appears useful to
                        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
                        features of the operating system, in
                        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>
                                <listitem><para>If possible, do not use
                                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
                                on boot, make sure to add a
                                <varname>WantedBy=multi-user.target</varname>
                                or
                                <varname>WantedBy=graphical.target</varname>
                                directive. To activate your socket on
                                boot, make sure to add
                                <varname>WantedBy=sockets.target</varname>. Usually,
                                you also want to make sure that when
                                your service is installed, your socket
                                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
                        package build), packages are recommended to
                        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>
                        by the administrator), symlinks should be
                        created in the systemd configuration
                        directories via the <command>enable</command>
                        command of the
                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                        tool to activate them automatically on
                        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],
     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>

                        <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>
                        <filename>.spec</filename> file, use snippets
                        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
                        upgrades, replace the
                        <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
                        time the unit file is installed, it will be
                        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
                compatible with traditional SysV init systems, it is
                not strictly necessary to port existing daemons to the
                new style. However, doing so offers additional
                functionality to the daemons as well as simplifying
                integration into new-style init systems.</para>

                <para>To port an existing SysV compatible daemon, the
                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
                        local system via local <constant>AF_UNIX</constant> sockets,
                        consider implementing socket-based activation
                        (see above). Usually, a minimal patch is
                        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
                        that the file system socket nodes for local
                        <constant>AF_UNIX</constant> sockets used in the socket-based
                        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>

        <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>,
                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>