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