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