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