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 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>.
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>
98 <listitem><para>Reset the signal mask
100 <function>sigprocmask()
</function>.
</para></listitem>
102 <listitem><para>Sanitize the
103 environment block, removing or
104 resetting environment variables that
105 might negatively impact daemon
106 runtime.
</para></listitem>
108 <listitem><para>Call
<function>fork()
</function>,
109 to create a background
110 process.
</para></listitem>
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>
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>
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>
130 <listitem><para>In the daemon process,
131 connect
<filename>/dev/null
</filename>
132 to standard input, output, and error.
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>
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>
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>
164 <listitem><para>In the daemon process,
165 drop privileges, if possible and
166 applicable.
</para></listitem>
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
175 <function>fork()
</function> and hence
176 available in both the original and the
177 daemon process.
</para></listitem>
180 <function>exit()
</function> in the
181 original process. The process that
182 invoked the daemon must be able to
184 <function>exit()
</function> happens
185 after initialization is complete and
186 all external communication channels
188 accessible.
</para></listitem>
191 <para>The BSD
<function>daemon()
</function> function should not be
192 used, as it implements only a subset of these steps.
</para>
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>
205 <title>New-Style Daemons
</title>
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>
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
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.
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.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>
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
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><4></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>
342 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para></listitem>
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>
354 <title>Activation
</title>
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
383 <title>Activation on Boot
</title>
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>
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>
408 <filename>multi-user.target
</filename> or
409 <filename>graphical.target
</filename>, which
410 are normally used as boot targets at system
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>
421 <title>Socket-Based Activation
</title>
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>
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>
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>
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
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
496 <filename>multi-user.target
</filename> or
497 suchlike) when one is installed in
498 <filename>sockets.target
</filename>.
</para>
502 <title>Bus-Based Activation
</title>
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
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>,
521 <varname>SystemdService=rtkit-daemon.service
</varname>
522 in that file to bind it to the systemd
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>
531 <title>Device-Based Activation
</title>
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
548 <varname>SYSTEMD_WANTS=
</varname>
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
562 <filename>bluetoothd.service
</filename> via
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
573 <title>Path-Based Activation
</title>
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
585 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
589 <title>Timer-Based Activation
</title>
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
597 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
601 <title>Other Forms of Activation
</title>
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
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>
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
653 <title>Integration with Systemd
</title>
656 <title>Writing Systemd Unit Files
</title>
658 <para>When writing systemd unit files, it is
659 recommended to consider the following
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>
671 <listitem><para>If your daemon
672 registers a D-Bus name on the bus,
674 <varname>Type=dbus
</varname> in the
676 possible.
</para></listitem>
678 <listitem><para>Make sure to set a
679 good human-readable description string
681 <varname>Description=
</varname>.
</para></listitem>
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>
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
694 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
695 or names introduced by your own
696 package to keep the unit file
698 system-independent.
</para></listitem>
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>
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
718 <filename>foo.service
</filename>, for
719 a hypothetical program
720 <filename>foo
</filename>.
</para></listitem>
726 <title>Installing Systemd Service Files
</title>
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
734 --variable=systemdsystemunitdir
</command> (for
735 system services) or
<command>pkg-config
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>
747 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
748 tool to activate them automatically on
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>
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)
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>
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
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>
787 <citerefentry project='die-net'
><refentrytitle>automake
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
790 <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
791 --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)
</programlisting>
793 <para>Finally, unit files should be installed in the system with an automake excerpt like the following:
</para>
795 <programlisting>if HAVE_SYSTEMD
796 systemdsystemunit_DATA = \
799 endif
</programlisting>
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
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>
812 <para>At the top of the file:
</para>
814 <programlisting>BuildRequires: systemd
815 %{?systemd_requires}
</programlisting>
817 <para>And as scriptlets, further down:
</para>
819 <programlisting>%post
820 %systemd_post foobar.service foobar.socket
823 %systemd_preun foobar.service foobar.socket
826 %systemd_postun
</programlisting>
828 <para>If the service shall be restarted during
829 upgrades, replace the
830 <literal>%postun
</literal> scriptlet above
831 with the following:
</para>
833 <programlisting>%postun
834 %systemd_postun_with_restart foobar.service
</programlisting>
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>
843 arguments.
<literal>%systemd_postun_with_restart
</literal>
844 expects the units to restart as
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>
853 <programlisting>%triggerun -- foobar
< 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>&1 || :
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>
874 <title>Porting Existing Daemons
</title>
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>
883 <para>To port an existing SysV compatible daemon, the
884 following steps are recommended:
</para>
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>
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>
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>
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>
937 <title>Placing Daemon Data
</title>
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>
945 <title>See Also
</title>
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>
projects / thirdparty / systemd.git / blob