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 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
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.
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.
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/>.
24 <refentry id="daemon">
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>daemon</refentrytitle>
42 <manvolnum>7</manvolnum>
46 <refname>daemon</refname>
47 <refpurpose>Writing and packaging system daemons</refpurpose>
51 <title>Description</title>
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>
66 <title>SysV Daemons</title>
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>
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>
90 <listitem><para>Reset all signal
91 handlers to their default. This is
92 best done by iterating through the
93 available signals up to the limit of
94 _NSIG and resetting them to
95 <constant>SIG_DFL</constant>.</para></listitem>
97 <listitem><para>Reset the signal mask
99 <function>sigprocmask()</function>.</para></listitem>
101 <listitem><para>Sanitize the
102 environment block, removing or
103 resetting environment variables that
104 might negatively impact daemon
105 runtime.</para></listitem>
107 <listitem><para>Call <function>fork()</function>,
108 to create a background
109 process.</para></listitem>
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>
116 <listitem><para>In the child, call
117 <function>fork()</function> again, to
118 ensure that the daemon can never re-acquire
119 a terminal again.</para></listitem>
121 <listitem><para>Call <function>exit()</function> in the
122 first child, so that only the second
123 child (the actual daemon process)
124 stays around. This ensures that the
125 daemon process is re-parented to
126 init/PID 1, as all daemons should
127 be.</para></listitem>
129 <listitem><para>In the daemon process,
130 connect <filename>/dev/null</filename>
132 STDERR.</para></listitem>
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>
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>
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 it is verified at the same time that
159 the PID previously stored in the PID
160 file no longer exists or belongs to a
161 foreign process. Commonly, some kind of
162 file locking is employed to implement
163 this logic.</para></listitem>
165 <listitem><para>In the daemon process,
166 drop privileges, if possible and
167 applicable.</para></listitem>
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
176 <function>fork()</function> and hence
177 available in both the original and the
178 daemon process.</para></listitem>
181 <function>exit()</function> in the
182 original process. The process that
183 invoked the daemon must be able to
185 <function>exit()</function> happens
186 after initialization is complete and
187 all external communication channels
189 accessible.</para></listitem>
192 <para>The BSD <function>daemon()</function> function should not be
193 used, as it implements only a subset of these steps.</para>
195 <para>A daemon that needs to provide
196 compatibility with SysV systems should
197 implement the scheme pointed out
198 above. However, it is recommended to make this
199 behavior optional and configurable via a
200 command line argument to ease debugging as
201 well as to simplify integration into systems
202 using systemd.</para>
206 <title>New-Style Daemons</title>
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>
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
225 <para>Note that new-style init systems
226 guarantee execution of daemon processes in
227 a clean process context: it is guaranteed that
228 the environment block is sanitized, that the
229 signal handlers and mask is reset and that no
230 left-over file descriptors are passed. Daemons
231 will be executed in their own session, and
232 STDIN/STDOUT/STDERR connected to
233 <filename>/dev/null</filename> unless
234 otherwise configured. The umask is reset.</para>
236 <para>It is recommended for new-style daemons
237 to implement the following:</para>
240 <listitem><para>If <constant>SIGTERM</constant> is
241 received, shut down the daemon and
242 exit cleanly.</para></listitem>
244 <listitem><para>If <constant>SIGHUP</constant> is received,
245 reload the configuration files, if
246 this applies.</para></listitem>
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>
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>
264 <listitem><para>For integration in
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>
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>
285 controls.</para></listitem>
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>
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>
317 <listitem><para>If applicable, a daemon
318 should notify the init system about
319 startup completion or status updates
321 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
322 interface.</para></listitem>
324 <listitem><para>Instead of using the
325 <function>syslog()</function> call to log directly to the
326 system syslog service, 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 "<4>"
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
342 <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
343 kind of logging may be enabled by
345 <varname>StandardError=syslog</varname>
346 in the service unit file. For details,
348 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
350 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
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>
362 <title>Activation</title>
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
391 <title>Activation on Boot</title>
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 ubiquitously 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>
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>
416 <filename>multi-user.target</filename> or
417 <filename>graphical.target</filename>, which
418 are normally used as boot targets at system
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>
429 <title>Socket-Based Activation</title>
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 as 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>
463 <para>New-style daemons which support socket
464 activation must be able to receive their
465 sockets from the init system instead 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>
471 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</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>
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
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
504 <filename>multi-user.target</filename> or
505 suchlike) when one is installed in
506 <filename>sockets.target</filename>.</para>
510 <title>Bus-Based Activation</title>
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
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>,
529 <varname>SystemdService=rtkit-daemon.service</varname>
530 in that file to bind it to the systemd
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>
539 <title>Device-Based Activation</title>
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
556 <varname>SYSTEMD_WANTS=</varname>
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
570 <filename>bluetoothd.service</filename> via
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
581 <title>Path-Based Activation</title>
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
593 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
597 <title>Timer-Based Activation</title>
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
605 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
609 <title>Other Forms of Activation</title>
611 <para>Other forms of activation have been
612 suggested and implemented in some
613 systems. However, there are often 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
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 bandwidth available to other processes, it
648 should be configured with
649 <varname>CPUSchedulingPolicy=idle</varname>
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
661 <title>Integration with Systemd</title>
664 <title>Writing Systemd Unit Files</title>
666 <para>When writing systemd unit files, it is
667 recommended to consider the following
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>
679 <listitem><para>If your daemon
680 registers a D-Bus name on the bus,
682 <varname>Type=dbus</varname> in the
684 possible.</para></listitem>
686 <listitem><para>Make sure to set a
687 good human-readable description string
689 <varname>Description=</varname>.</para></listitem>
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>
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
702 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
703 or names introduced by your own
704 package to keep the unit file
706 system-independent.</para></listitem>
708 <listitem><para>Make sure to include
709 an <literal>[Install]</literal>
710 section including installation
711 information for the unit file. See
712 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
713 for details. To activate your service
714 on boot, make sure to add a
715 <varname>WantedBy=multi-user.target</varname>
717 <varname>WantedBy=graphical.target</varname>
718 directive. To activate your socket on
719 boot, make sure to add
720 <varname>WantedBy=sockets.target</varname>. Usually,
721 you also want to make sure that when
722 your service is installed, your socket
723 is installed too, hence add
724 <varname>Also=foo.socket</varname> in
726 <filename>foo.service</filename>, for
727 a hypothetical program
728 <filename>foo</filename>.</para></listitem>
734 <title>Installing Systemd Service Files</title>
736 <para>At the build installation time
737 (e.g. <command>make install</command> during
738 package build), packages are recommended to
739 install their systemd unit files in the
740 directory returned by <command>pkg-config
742 --variable=systemdsystemunitdir</command> (for
743 system services) or <command>pkg-config
745 --variable=systemduserunitdir</command>
746 (for user services). This will make the
747 services available in the system on explicit
748 request but not activate them automatically
749 during boot. Optionally, during package
750 installation (e.g. <command>rpm -i</command>
751 by the administrator), symlinks should be
752 created in the systemd configuration
753 directories via the <command>enable</command>
755 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
756 tool to activate them automatically on
760 <citerefentry><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
761 are recommended to use a configure script
762 excerpt like the following to determine the
763 unit installation path during source
764 configuration:</para>
766 <programlisting>PKG_PROG_PKG_CONFIG
767 AC_ARG_WITH([systemdsystemunitdir],
768 AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
769 [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
770 if test "x$with_systemdsystemunitdir" != xno; then
771 AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
773 AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ])</programlisting>
775 <para>This snippet allows automatic
776 installation of the unit files on systemd
777 machines, and optionally allows their
778 installation even on machines lacking
779 systemd. (Modification of this snippet for the
780 user unit directory is left as an exercise for the
783 <para>Additionally, to ensure that
784 <command>make distcheck</command> continues to
785 work, it is recommended to add the following
786 to the top-level <filename>Makefile.am</filename>
788 <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
791 <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
792 --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>
794 <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
796 <programlisting>if HAVE_SYSTEMD
797 systemdsystemunit_DATA = \
800 endif</programlisting>
803 <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
804 <filename>.spec</filename> file, use snippets
805 like the following to enable/disable the
807 installation/deinstallation. This makes use of
808 the RPM macros shipped along systemd. Consult
809 the packaging guidelines of your distribution
810 for details and the equivalent for other
811 package managers.</para>
813 <para>At the top of the file:</para>
815 <programlisting>BuildRequires: systemd
816 %{?systemd_requires}</programlisting>
818 <para>And as scriptlets, further down:</para>
820 <programlisting>%post
821 %systemd_post foobar.service foobar.socket
824 %systemd_preun foobar.service foobar.socket
827 %systemd_postun</programlisting>
829 <para>If the service shall be restarted during
830 upgrades, replace the
831 <literal>%postun</literal> scriptlet above
832 with the following:</para>
834 <programlisting>%postun
835 %systemd_postun_with_restart foobar.service</programlisting>
838 <literal>%systemd_post</literal> and
839 <literal>%systemd_preun</literal> expect the
840 names of all units that are installed/removed
841 as arguments, separated by
842 spaces. <literal>%systemd_postun</literal>
844 arguments. <literal>%systemd_postun_with_restart</literal>
845 expects the units to restart as
848 <para>To facilitate upgrades from a package
849 version that shipped only SysV init scripts to
850 a package version that ships both a SysV init
851 script and a native systemd service file, use
852 a fragment like the following:</para>
854 <programlisting>%triggerun -- foobar < 0.47.11-1
855 if /sbin/chkconfig --level 5 foobar ; then
856 /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || :
859 <para>Where 0.47.11-1 is the first package
860 version that includes the native unit
861 file. This fragment will ensure that the first
862 time the unit file is installed, it will be
863 enabled if and only if the SysV init script is
864 enabled, thus making sure that the enable
865 status is not changed. Note that
866 <command>chkconfig</command> is a command
867 specific to Fedora which can be used to check
868 whether a SysV init script is enabled. Other
869 operating systems will have to use different
870 commands here.</para>
875 <title>Porting Existing Daemons</title>
877 <para>Since new-style init systems such as systemd are
878 compatible with traditional SysV init systems, it is
879 not strictly necessary to port existing daemons to the
880 new style. However, doing so offers additional
881 functionality to the daemons as well as simplifying
882 integration into new-style init systems.</para>
884 <para>To port an existing SysV compatible daemon, the
885 following steps are recommended:</para>
888 <listitem><para>If not already implemented,
889 add an optional command line switch to the
890 daemon to disable daemonization. This is
891 useful not only for using the daemon in
892 new-style init systems, but also to ease
893 debugging.</para></listitem>
895 <listitem><para>If the daemon offers
896 interfaces to other software running on the
897 local system via local <constant>AF_UNIX</constant> sockets,
898 consider implementing socket-based activation
899 (see above). Usually, a minimal patch is
900 sufficient to implement this: Extend the
901 socket creation in the daemon code so that
902 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
903 is checked for already passed sockets
904 first. If sockets are passed (i.e. when
905 <function>sd_listen_fds()</function> returns a
906 positive value), skip the socket creation step
907 and use the passed sockets. Secondly, ensure
908 that the file system socket nodes for local
909 <constant>AF_UNIX</constant> sockets used in the socket-based
910 activation are not removed when the daemon
911 shuts down, if sockets have been
912 passed. Third, if the daemon normally closes
913 all remaining open file descriptors as part of
914 its initialization, the sockets passed from
915 the init system must be spared. Since
916 new-style init systems guarantee that no
917 left-over file descriptors are passed to
918 executed processes, it might be a good choice
919 to simply skip the closing of all remaining
920 open file descriptors if sockets are
921 passed.</para></listitem>
923 <listitem><para>Write and install a systemd
924 unit file for the service (and the sockets if
925 socket-based activation is used, as well as a
926 path unit file, if the daemon processes a
927 spool directory), see above for
928 details.</para></listitem>
930 <listitem><para>If the daemon exposes
931 interfaces via D-Bus, write and install a
932 D-Bus activation file for the service, see
933 above for details.</para></listitem>
938 <title>See Also</title>
940 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
941 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
942 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
943 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
944 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
945 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>