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">
6 SPDX-License-Identifier: LGPL-2.1+
13 <productname>systemd
</productname>
17 <refentrytitle>daemon
</refentrytitle>
18 <manvolnum>7</manvolnum>
22 <refname>daemon
</refname>
23 <refpurpose>Writing and packaging system daemons
</refpurpose>
27 <title>Description
</title>
29 <para>A daemon is a service process that runs in the background
30 and supervises the system or provides functionality to other
31 processes. Traditionally, daemons are implemented following a
32 scheme originating in SysV Unix. Modern daemons should follow a
33 simpler yet more powerful scheme (here called
"new-style"
34 daemons), as implemented by
35 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
36 This manual page covers both schemes, and in particular includes
37 recommendations for daemons that shall be included in the systemd
41 <title>SysV Daemons
</title>
43 <para>When a traditional SysV daemon starts, it should execute
44 the following steps as part of the initialization. Note that
45 these steps are unnecessary for new-style daemons (see below),
46 and should only be implemented if compatibility with SysV is
50 <listitem><para>Close all open file descriptors except
51 standard input, output, and error (i.e. the first three file
52 descriptors
0,
1,
2). This ensures that no accidentally passed
53 file descriptor stays around in the daemon process. On Linux,
54 this is best implemented by iterating through
55 <filename>/proc/self/fd
</filename>, with a fallback of
56 iterating from file descriptor
3 to the value returned by
57 <function>getrlimit()
</function> for
58 <constant>RLIMIT_NOFILE
</constant>.
</para></listitem>
60 <listitem><para>Reset all signal handlers to their default.
61 This is best done by iterating through the available signals
62 up to the limit of
<constant>_NSIG
</constant> and resetting
63 them to
<constant>SIG_DFL
</constant>.
</para></listitem>
65 <listitem><para>Reset the signal mask
67 <function>sigprocmask()
</function>.
</para></listitem>
69 <listitem><para>Sanitize the environment block, removing or
70 resetting environment variables that might negatively impact
71 daemon runtime.
</para></listitem>
73 <listitem><para>Call
<function>fork()
</function>, to create a
74 background process.
</para></listitem>
76 <listitem><para>In the child, call
77 <function>setsid()
</function> to detach from any terminal and
78 create an independent session.
</para></listitem>
80 <listitem><para>In the child, call
<function>fork()
</function>
81 again, to ensure that the daemon can never re-acquire a
82 terminal again.
</para></listitem>
84 <listitem><para>Call
<function>exit()
</function> in the first
85 child, so that only the second child (the actual daemon
86 process) stays around. This ensures that the daemon process is
87 re-parented to init/PID
1, as all daemons should
90 <listitem><para>In the daemon process, connect
91 <filename>/dev/null
</filename> to standard input, output, and
92 error.
</para></listitem>
94 <listitem><para>In the daemon process, reset the umask to
0,
95 so that the file modes passed to
<function>open()
</function>,
96 <function>mkdir()
</function> and suchlike directly control the
97 access mode of the created files and
98 directories.
</para></listitem>
100 <listitem><para>In the daemon process, change the current
101 directory to the root directory (/), in order to avoid that
102 the daemon involuntarily blocks mount points from being
103 unmounted.
</para></listitem>
105 <listitem><para>In the daemon process, write the daemon PID
106 (as returned by
<function>getpid()
</function>) to a PID file,
107 for example
<filename>/run/foobar.pid
</filename> (for a
108 hypothetical daemon
"foobar") to ensure that the daemon cannot
109 be started more than once. This must be implemented in
110 race-free fashion so that the PID file is only updated when it
111 is verified at the same time that the PID previously stored in
112 the PID file no longer exists or belongs to a foreign
113 process.
</para></listitem>
115 <listitem><para>In the daemon process, drop privileges, if
116 possible and applicable.
</para></listitem>
118 <listitem><para>From the daemon process, notify the original
119 process started that initialization is complete. This can be
120 implemented via an unnamed pipe or similar communication
121 channel that is created before the first
122 <function>fork()
</function> and hence available in both the
123 original and the daemon process.
</para></listitem>
125 <listitem><para>Call
<function>exit()
</function> in the
126 original process. The process that invoked the daemon must be
127 able to rely on that this
<function>exit()
</function> happens
128 after initialization is complete and all external
129 communication channels are established and
130 accessible.
</para></listitem>
133 <para>The BSD
<function>daemon()
</function> function should not
134 be used, as it implements only a subset of these steps.
</para>
136 <para>A daemon that needs to provide compatibility with SysV
137 systems should implement the scheme pointed out above. However,
138 it is recommended to make this behavior optional and
139 configurable via a command line argument to ease debugging as
140 well as to simplify integration into systems using
145 <title>New-Style Daemons
</title>
147 <para>Modern services for Linux should be implemented as
148 new-style daemons. This makes it easier to supervise and control
149 them at runtime and simplifies their implementation.
</para>
151 <para>For developing a new-style daemon, none of the
152 initialization steps recommended for SysV daemons need to be
153 implemented. New-style init systems such as systemd make all of
154 them redundant. Moreover, since some of these steps interfere
155 with process monitoring, file descriptor passing and other
156 functionality of the init system, it is recommended not to
157 execute them when run as new-style service.
</para>
159 <para>Note that new-style init systems guarantee execution of daemon processes in a clean process context: it is
160 guaranteed that the environment block is sanitized, that the signal handlers and mask is reset and that no
161 left-over file descriptors are passed. Daemons will be executed in their own session, with standard input
162 connected to
<filename>/dev/null
</filename> and standard output/error connected to the
163 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
164 logging service, unless otherwise configured. The umask is reset.
167 <para>It is recommended for new-style daemons to implement the
171 <listitem><para>If
<constant>SIGTERM
</constant> is received,
172 shut down the daemon and exit cleanly.
</para></listitem>
174 <listitem><para>If
<constant>SIGHUP
</constant> is received,
175 reload the configuration files, if this
176 applies.
</para></listitem>
178 <listitem><para>Provide a correct exit code from the main
179 daemon process, as this is used by the init system to detect
180 service errors and problems. It is recommended to follow the
181 exit code scheme as defined in the
<ulink
182 url=
"http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
183 recommendations for SysV init
184 scripts
</ulink>.
</para></listitem>
186 <listitem><para>If possible and applicable, expose the
187 daemon's control interface via the D-Bus IPC system and grab a
188 bus name as last step of initialization.
</para></listitem>
190 <listitem><para>For integration in systemd, provide a
191 <filename>.service
</filename> unit file that carries
192 information about starting, stopping and otherwise maintaining
194 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
195 for details.
</para></listitem>
197 <listitem><para>As much as possible, rely on the init system's
198 functionality to limit the access of the daemon to files,
199 services and other resources, i.e. in the case of systemd,
200 rely on systemd's resource limit control instead of
201 implementing your own, rely on systemd's privilege dropping
202 code instead of implementing it in the daemon, and similar.
204 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
205 for the available controls.
</para></listitem>
207 <listitem><para>If D-Bus is used, make your daemon
208 bus-activatable by supplying a D-Bus service activation
209 configuration file. This has multiple advantages: your daemon
210 may be started lazily on-demand; it may be started in parallel
211 to other daemons requiring it — which maximizes
212 parallelization and boot-up speed; your daemon can be
213 restarted on failure without losing any bus requests, as the
214 bus queues requests for activatable services. See below for
215 details.
</para></listitem>
217 <listitem><para>If your daemon provides services to other
218 local processes or remote clients via a socket, it should be
219 made socket-activatable following the scheme pointed out
220 below. Like D-Bus activation, this enables on-demand starting
221 of services as well as it allows improved parallelization of
222 service start-up. Also, for state-less protocols (such as
223 syslog, DNS), a daemon implementing socket-based activation
224 can be restarted without losing a single request. See below
225 for details.
</para></listitem>
227 <listitem><para>If applicable, a daemon should notify the init
228 system about startup completion or status updates via the
229 <citerefentry><refentrytitle>sd_notify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
230 interface.
</para></listitem>
232 <listitem><para>Instead of using the
233 <function>syslog()
</function> call to log directly to the
234 system syslog service, a new-style daemon may choose to simply
235 log to standard error via
<function>fprintf()
</function>,
236 which is then forwarded to syslog by the init system. If log
237 levels are necessary, these can be encoded by prefixing
238 individual log lines with strings like
239 <literal><4></literal> (for log level
4 "WARNING" in the
240 syslog priority scheme), following a similar style as the
241 Linux kernel's
<function>printk()
</function> level system. For
243 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
245 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem>
249 <para>These recommendations are similar but not identical to the
251 url=
"https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple
252 MacOS X Daemon Requirements
</ulink>.
</para>
257 <title>Activation
</title>
259 <para>New-style init systems provide multiple additional
260 mechanisms to activate services, as detailed below. It is common
261 that services are configured to be activated via more than one
262 mechanism at the same time. An example for systemd:
263 <filename>bluetoothd.service
</filename> might get activated either
264 when Bluetooth hardware is plugged in, or when an application
265 accesses its programming interfaces via D-Bus. Or, a print server
266 daemon might get activated when traffic arrives at an IPP port, or
267 when a printer is plugged in, or when a file is queued in the
268 printer spool directory. Even for services that are intended to be
269 started on system bootup unconditionally, it is a good idea to
270 implement some of the various activation schemes outlined below,
271 in order to maximize parallelization. If a daemon implements a
272 D-Bus service or listening socket, implementing the full bus and
273 socket activation scheme allows starting of the daemon with its
274 clients in parallel (which speeds up boot-up), since all its
275 communication channels are established already, and no request is
276 lost because client requests will be queued by the bus system (in
277 case of D-Bus) or the kernel (in case of sockets) until the
278 activation is completed.
</para>
281 <title>Activation on Boot
</title>
283 <para>Old-style daemons are usually activated exclusively on
284 boot (and manually by the administrator) via SysV init scripts,
285 as detailed in the
<ulink
286 url=
"http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
287 Linux Standard Base Core Specification
</ulink>. This method of
288 activation is supported ubiquitously on Linux init systems, both
289 old-style and new-style systems. Among other issues, SysV init
290 scripts have the disadvantage of involving shell scripts in the
291 boot process. New-style init systems generally employ updated
292 versions of activation, both during boot-up and during runtime
293 and using more minimal service description files.
</para>
295 <para>In systemd, if the developer or administrator wants to
296 make sure that a service or other unit is activated
297 automatically on boot, it is recommended to place a symlink to
298 the unit file in the
<filename>.wants/
</filename> directory of
299 either
<filename>multi-user.target
</filename> or
300 <filename>graphical.target
</filename>, which are normally used
301 as boot targets at system startup. See
302 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
303 for details about the
<filename>.wants/
</filename> directories,
305 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
306 for details about the two boot targets.
</para>
311 <title>Socket-Based Activation
</title>
313 <para>In order to maximize the possible parallelization and
314 robustness and simplify configuration and development, it is
315 recommended for all new-style daemons that communicate via
316 listening sockets to employ socket-based activation. In a
317 socket-based activation scheme, the creation and binding of the
318 listening socket as primary communication channel of daemons to
319 local (and sometimes remote) clients is moved out of the daemon
320 code and into the init system. Based on per-daemon
321 configuration, the init system installs the sockets and then
322 hands them off to the spawned process as soon as the respective
323 daemon is to be started. Optionally, activation of the service
324 can be delayed until the first inbound traffic arrives at the
325 socket to implement on-demand activation of daemons. However,
326 the primary advantage of this scheme is that all providers and
327 all consumers of the sockets can be started in parallel as soon
328 as all sockets are established. In addition to that, daemons can
329 be restarted with losing only a minimal number of client
330 transactions, or even any client request at all (the latter is
331 particularly true for state-less protocols, such as DNS or
332 syslog), because the socket stays bound and accessible during
333 the restart, and all requests are queued while the daemon cannot
336 <para>New-style daemons which support socket activation must be
337 able to receive their sockets from the init system instead of
338 creating and binding them themselves. For details about the
339 programming interfaces for this scheme provided by systemd, see
340 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
342 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
343 For details about porting existing daemons to socket-based
344 activation, see below. With minimal effort, it is possible to
345 implement socket-based activation in addition to traditional
346 internal socket creation in the same codebase in order to
347 support both new-style and old-style init systems from the same
348 daemon binary.
</para>
350 <para>systemd implements socket-based activation via
351 <filename>.socket
</filename> units, which are described in
352 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
353 When configuring socket units for socket-based activation, it is
354 essential that all listening sockets are pulled in by the
355 special target unit
<filename>sockets.target
</filename>. It is
356 recommended to place a
357 <varname>WantedBy=sockets.target
</varname> directive in the
358 <literal>[Install]
</literal> section to automatically add such a
359 dependency on installation of a socket unit. Unless
360 <varname>DefaultDependencies=no
</varname> is set, the necessary
361 ordering dependencies are implicitly created for all socket
362 units. For more information about
363 <filename>sockets.target
</filename>, see
364 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
365 It is not necessary or recommended to place any additional
366 dependencies on socket units (for example from
367 <filename>multi-user.target
</filename> or suchlike) when one is
368 installed in
<filename>sockets.target
</filename>.
</para>
372 <title>Bus-Based Activation
</title>
374 <para>When the D-Bus IPC system is used for communication with
375 clients, new-style daemons should employ bus activation so that
376 they are automatically activated when a client application
377 accesses their IPC interfaces. This is configured in D-Bus
378 service files (not to be confused with systemd service unit
379 files!). To ensure that D-Bus uses systemd to start-up and
380 maintain the daemon, use the
<varname>SystemdService=
</varname>
381 directive in these service files to configure the matching
382 systemd service for a D-Bus service. e.g.: For a D-Bus service
383 whose D-Bus activation file is named
384 <filename>org.freedesktop.RealtimeKit.service
</filename>, make
386 <varname>SystemdService=rtkit-daemon.service
</varname> in that
387 file to bind it to the systemd service
388 <filename>rtkit-daemon.service
</filename>. This is needed to
389 make sure that the daemon is started in a race-free fashion when
390 activated via multiple mechanisms simultaneously.
</para>
394 <title>Device-Based Activation
</title>
396 <para>Often, daemons that manage a particular type of hardware
397 should be activated only when the hardware of the respective
398 kind is plugged in or otherwise becomes available. In a
399 new-style init system, it is possible to bind activation to
400 hardware plug/unplug events. In systemd, kernel devices
401 appearing in the sysfs/udev device tree can be exposed as units
402 if they are tagged with the string
<literal>systemd
</literal>.
403 Like any other kind of unit, they may then pull in other units
404 when activated (i.e. plugged in) and thus implement device-based
405 activation. systemd dependencies may be encoded in the udev
406 database via the
<varname>SYSTEMD_WANTS=
</varname> property. See
407 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
408 for details. Often, it is nicer to pull in services from devices
409 only indirectly via dedicated targets. Example: Instead of
410 pulling in
<filename>bluetoothd.service
</filename> from all the
411 various bluetooth dongles and other hardware available, pull in
412 bluetooth.target from them and
413 <filename>bluetoothd.service
</filename> from that target. This
414 provides for nicer abstraction and gives administrators the
415 option to enable
<filename>bluetoothd.service
</filename> via
416 controlling a
<filename>bluetooth.target.wants/
</filename>
417 symlink uniformly with a command like
<command>enable
</command>
419 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
420 instead of manipulating the udev ruleset.
</para>
424 <title>Path-Based Activation
</title>
426 <para>Often, runtime of daemons processing spool files or
427 directories (such as a printing system) can be delayed until
428 these file system objects change state, or become non-empty.
429 New-style init systems provide a way to bind service activation
430 to file system changes. systemd implements this scheme via
431 path-based activation configured in
<filename>.path
</filename>
432 units, as outlined in
433 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
437 <title>Timer-Based Activation
</title>
439 <para>Some daemons that implement clean-up jobs that are
440 intended to be executed in regular intervals benefit from
441 timer-based activation. In systemd, this is implemented via
442 <filename>.timer
</filename> units, as described in
443 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
447 <title>Other Forms of Activation
</title>
449 <para>Other forms of activation have been suggested and
450 implemented in some systems. However, there are often simpler or
451 better alternatives, or they can be put together of combinations
452 of the schemes above. Example: Sometimes, it appears useful to
453 start daemons or
<filename>.socket
</filename> units when a
454 specific IP address is configured on a network interface,
455 because network sockets shall be bound to the address. However,
456 an alternative to implement this is by utilizing the Linux
457 <constant>IP_FREEBIND
</constant> socket option, as accessible
458 via
<varname>FreeBind=yes
</varname> in systemd socket files (see
459 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
460 for details). This option, when enabled, allows sockets to be
461 bound to a non-local, not configured IP address, and hence
462 allows bindings to a particular IP address before it actually
463 becomes available, making such an explicit dependency to the
464 configured address redundant. Another often suggested trigger
465 for service activation is low system load. However, here too, a
466 more convincing approach might be to make proper use of features
467 of the operating system, in particular, the CPU or I/O scheduler
468 of Linux. Instead of scheduling jobs from userspace based on
469 monitoring the OS scheduler, it is advisable to leave the
470 scheduling of processes to the OS scheduler itself. systemd
471 provides fine-grained access to the CPU and I/O schedulers. If a
472 process executed by the init system shall not negatively impact
473 the amount of CPU or I/O bandwidth available to other processes,
474 it should be configured with
475 <varname>CPUSchedulingPolicy=idle
</varname> and/or
476 <varname>IOSchedulingClass=idle
</varname>. Optionally, this may
477 be combined with timer-based activation to schedule background
478 jobs during runtime and with minimal impact on the system, and
479 remove it from the boot phase itself.
</para>
484 <title>Integration with systemd
</title>
487 <title>Writing systemd Unit Files
</title>
489 <para>When writing systemd unit files, it is recommended to
490 consider the following suggestions:
</para>
493 <listitem><para>If possible, do not use the
494 <varname>Type=forking
</varname> setting in service files. But
495 if you do, make sure to set the PID file path using
496 <varname>PIDFile=
</varname>. See
497 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
498 for details.
</para></listitem>
500 <listitem><para>If your daemon registers a D-Bus name on the
501 bus, make sure to use
<varname>Type=dbus
</varname> in the
502 service file if possible.
</para></listitem>
504 <listitem><para>Make sure to set a good human-readable
505 description string with
506 <varname>Description=
</varname>.
</para></listitem>
508 <listitem><para>Do not disable
509 <varname>DefaultDependencies=
</varname>, unless you really
510 know what you do and your unit is involved in early boot or
511 late system shutdown.
</para></listitem>
513 <listitem><para>Normally, little if any dependencies should
514 need to be defined explicitly. However, if you do configure
515 explicit dependencies, only refer to unit names listed on
516 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
517 or names introduced by your own package to keep the unit file
518 operating system-independent.
</para></listitem>
520 <listitem><para>Make sure to include an
521 <literal>[Install]
</literal> section including installation
522 information for the unit file. See
523 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
524 for details. To activate your service on boot, make sure to
525 add a
<varname>WantedBy=multi-user.target
</varname> or
526 <varname>WantedBy=graphical.target
</varname> directive. To
527 activate your socket on boot, make sure to add
528 <varname>WantedBy=sockets.target
</varname>. Usually, you also
529 want to make sure that when your service is installed, your
530 socket is installed too, hence add
531 <varname>Also=foo.socket
</varname> in your service file
532 <filename>foo.service
</filename>, for a hypothetical program
533 <filename>foo
</filename>.
</para></listitem>
539 <title>Installing systemd Service Files
</title>
541 <para>At the build installation time (e.g.
<command>make
542 install
</command> during package build), packages are
543 recommended to install their systemd unit files in the directory
544 returned by
<command>pkg-config systemd
545 --variable=systemdsystemunitdir
</command> (for system services)
546 or
<command>pkg-config systemd
547 --variable=systemduserunitdir
</command> (for user services).
548 This will make the services available in the system on explicit
549 request but not activate them automatically during boot.
550 Optionally, during package installation (e.g.
<command>rpm
551 -i
</command> by the administrator), symlinks should be created
552 in the systemd configuration directories via the
553 <command>enable
</command> command of the
554 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
555 tool to activate them automatically on boot.
</para>
558 <citerefentry project='die-net'
><refentrytitle>autoconf
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
559 are recommended to use a configure script
560 excerpt like the following to determine the
561 unit installation path during source
562 configuration:
</para>
564 <programlisting>PKG_PROG_PKG_CONFIG
565 AC_ARG_WITH([systemdsystemunitdir],
566 [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],,
567 [with_systemdsystemunitdir=auto])
568 AS_IF([test
"x$with_systemdsystemunitdir" =
"xyes" -o
"x$with_systemdsystemunitdir" =
"xauto"], [
569 def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)
571 AS_IF([test
"x$def_systemdsystemunitdir" =
"x"],
572 [AS_IF([test
"x$with_systemdsystemunitdir" =
"xyes"],
573 [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])])
574 with_systemdsystemunitdir=no],
575 [
with_systemdsystemunitdir=
"$def_systemdsystemunitdir"])])
576 AS_IF([test
"x$with_systemdsystemunitdir" !=
"xno"],
577 [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])])
578 AM_CONDITIONAL([HAVE_SYSTEMD], [test
"x$with_systemdsystemunitdir" !=
"xno"])
</programlisting>
580 <para>This snippet allows automatic
581 installation of the unit files on systemd
582 machines, and optionally allows their
583 installation even on machines lacking
584 systemd. (Modification of this snippet for the
585 user unit directory is left as an exercise for the
588 <para>Additionally, to ensure that
589 <command>make distcheck
</command> continues to
590 work, it is recommended to add the following
591 to the top-level
<filename>Makefile.am
</filename>
593 <citerefentry project='die-net'
><refentrytitle>automake
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
596 <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
597 --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)
</programlisting>
599 <para>Finally, unit files should be installed in the system with an automake excerpt like the following:
</para>
601 <programlisting>if HAVE_SYSTEMD
602 systemdsystemunit_DATA = \
605 endif
</programlisting>
608 <citerefentry project='die-net'
><refentrytitle>rpm
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
609 <filename>.spec
</filename> file, use snippets like the following
610 to enable/disable the service during
611 installation/deinstallation. This makes use of the RPM macros
612 shipped along systemd. Consult the packaging guidelines of your
613 distribution for details and the equivalent for other package
616 <para>At the top of the file:
</para>
618 <programlisting>BuildRequires: systemd
619 %{?systemd_requires}
</programlisting>
621 <para>And as scriptlets, further down:
</para>
623 <programlisting>%post
624 %systemd_post foobar.service foobar.socket
627 %systemd_preun foobar.service foobar.socket
630 %systemd_postun
</programlisting>
632 <para>If the service shall be restarted during upgrades, replace
633 the
<literal>%postun
</literal> scriptlet above with the
636 <programlisting>%postun
637 %systemd_postun_with_restart foobar.service
</programlisting>
639 <para>Note that
<literal>%systemd_post
</literal> and
640 <literal>%systemd_preun
</literal> expect the names of all units
641 that are installed/removed as arguments, separated by spaces.
642 <literal>%systemd_postun
</literal> expects no arguments.
643 <literal>%systemd_postun_with_restart
</literal> expects the
644 units to restart as arguments.
</para>
646 <para>To facilitate upgrades from a package version that shipped
647 only SysV init scripts to a package version that ships both a
648 SysV init script and a native systemd service file, use a
649 fragment like the following:
</para>
651 <programlisting>%triggerun -- foobar
< 0.47.11-
1
652 if /sbin/chkconfig --level
5 foobar ; then
653 /bin/systemctl --no-reload enable foobar.service foobar.socket
>/dev/null
2>&1 || :
656 <para>Where
0.47.11-
1 is the first package version that includes
657 the native unit file. This fragment will ensure that the first
658 time the unit file is installed, it will be enabled if and only
659 if the SysV init script is enabled, thus making sure that the
660 enable status is not changed. Note that
661 <command>chkconfig
</command> is a command specific to Fedora
662 which can be used to check whether a SysV init script is
663 enabled. Other operating systems will have to use different
664 commands here.
</para>
669 <title>Porting Existing Daemons
</title>
671 <para>Since new-style init systems such as systemd are compatible
672 with traditional SysV init systems, it is not strictly necessary
673 to port existing daemons to the new style. However, doing so
674 offers additional functionality to the daemons as well as
675 simplifying integration into new-style init systems.
</para>
677 <para>To port an existing SysV compatible daemon, the following
678 steps are recommended:
</para>
681 <listitem><para>If not already implemented, add an optional
682 command line switch to the daemon to disable daemonization. This
683 is useful not only for using the daemon in new-style init
684 systems, but also to ease debugging.
</para></listitem>
686 <listitem><para>If the daemon offers interfaces to other
687 software running on the local system via local
688 <constant>AF_UNIX
</constant> sockets, consider implementing
689 socket-based activation (see above). Usually, a minimal patch is
690 sufficient to implement this: Extend the socket creation in the
692 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
693 is checked for already passed sockets first. If sockets are
694 passed (i.e. when
<function>sd_listen_fds()
</function> returns a
695 positive value), skip the socket creation step and use the
696 passed sockets. Secondly, ensure that the file system socket
697 nodes for local
<constant>AF_UNIX
</constant> sockets used in the
698 socket-based activation are not removed when the daemon shuts
699 down, if sockets have been passed. Third, if the daemon normally
700 closes all remaining open file descriptors as part of its
701 initialization, the sockets passed from the init system must be
702 spared. Since new-style init systems guarantee that no left-over
703 file descriptors are passed to executed processes, it might be a
704 good choice to simply skip the closing of all remaining open
705 file descriptors if sockets are passed.
</para></listitem>
707 <listitem><para>Write and install a systemd unit file for the
708 service (and the sockets if socket-based activation is used, as
709 well as a path unit file, if the daemon processes a spool
710 directory), see above for details.
</para></listitem>
712 <listitem><para>If the daemon exposes interfaces via D-Bus,
713 write and install a D-Bus activation file for the service, see
714 above for details.
</para></listitem>
719 <title>Placing Daemon Data
</title>
721 <para>It is recommended to follow the general guidelines for
722 placing package files, as discussed in
723 <citerefentry><refentrytitle>file-hierarchy
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
727 <title>See Also
</title>
729 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
730 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
731 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
732 <citerefentry><refentrytitle>sd_notify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
733 <citerefentry><refentrytitle>daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
734 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
735 <citerefentry><refentrytitle>file-hierarchy
</refentrytitle><manvolnum>7</manvolnum></citerefentry>