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 General Public License as published by
12 the Free Software Foundation; either version 2 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 General Public License for more details.
20 You should have received a copy of the GNU General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
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 SIG_DFL.
</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 the daemon can never re-aquire
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 reparented 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 at the same time it is verified that
159 the PID previously stored in the PID
160 file no longer exists or belongs to a
161 foreign process. Commonly some kind of
162 file locking is employed to implement
163 this logic.
</para></listitem>
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 behaviour optional and configurable via a
200 command line argument, to ease debugging as
201 well as to simplify integration into systems
202 using systemd.
</para>
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 clean process contexts: it is guaranteed that
228 the environment block is sanitized, that the
229 signal handlers and mask is reset and that no
230 left-over file descriptors are passed. Daemons
231 will be executed in their own session, and
232 STDIN/STDOUT/STDERR connected to
233 <filename>/dev/null
</filename> unless
234 otherwise configured. The umask is reset.
</para>
236 <para>It is recommended for new-style daemons
237 to implement the following:
</para>
240 <listitem><para>If SIGTERM is
241 received, shut down the daemon and
242 exit cleanly.
</para></listitem>
244 <listitem><para>If SIGHUP 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 systemd's
275 functionality to limit the access of
276 the daemon to files, services and
277 other resources. i.e. in the case of
278 systemd, rely on systemd's resource
279 limit control instead of implementing
280 your own, rely on systemd's privilege
281 dropping code instead of implementing
282 it in the daemon, and similar. See
283 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
285 controls.
</para></listitem>
287 <listitem><para>If D-Bus is used, make
288 your daemon bus-activatable, via
289 supplying a D-Bus service activation
290 configuration file. This has multiple
291 advantages: your daemon may be started
292 lazily on-demand; it may be started in
293 parallel to other daemons requiring it
294 -- which maximizes parallelization and
295 boot-up speed; your daemon can be
296 restarted on failure, without losing
297 any bus requests, as the bus queues
298 requests for activatable services. See
299 below for details.
</para></listitem>
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 logger, a new-style daemon may
327 choose to simply log to STDERR via
328 <function>fprintf()
</function>, which is then forwarded to
329 syslog by the init system. If log
330 priorities are necessary these can be
331 encoded by prefixing individual log
332 lines with strings like
"<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>7</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 ubiquitiously on Linux
401 init systems, both old-style and new-style
402 systems. Among other issues SysV init scripts
403 have the disadvantage of involving shell
404 scripts in the boot process. New-style init
405 systems generally employ updated versions of
406 activation, both during boot-up and during
407 runtime and using more minimal service
408 description files.
</para>
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 als all sockets
453 are established. In addition to that daemons
454 can be restarted with losing only a minimal
455 number of client transactions or even any
456 client request at all (the latter is
457 particularly true for state-less protocols,
458 such as DNS or syslog), because the socket
459 stays bound and accessible during the restart,
460 and all requests are queued while the daemon
461 cannot process them.
</para>
463 <para>New-style daemons which support socket
464 activation must be able to receive their
465 sockets from the init system, instead of of
466 creating and binding them themselves. For
467 details about the programming interfaces for
468 this scheme provided by systemd see
469 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
471 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For
472 details about porting existing daemons to
473 socket-based activation see below. With
474 minimal effort it is possible to implement
475 socket-based activation in addition to
476 traditional internal socket creation in the
477 same codebase in order to support both
478 new-style and old-style init systems from the
479 same daemon binary.
</para>
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 systemd,
547 kernel devices appearing in the sysfs/udev
548 device tree can be exposed as units if they
549 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 tool like
574 <citerefentry><refentrytitle>systemd-install
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
575 instead of manipulating the udev
580 <title>Path-Based Activation
</title>
582 <para>Often, runtime of daemons processing
583 spool files or directories (such as a printing
584 system) can be delayed until these file system
585 objects change state, or become
586 non-empty. New-style init systems provide a
587 way to bind service activation to file system
588 changes. systemd implements this scheme via
589 path-based activation configured in
590 <filename>.path
</filename> units, as outlined
592 <citerefentry><refentrytitle>systemd.path
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
596 <title>Timer-Based Activation
</title>
598 <para>Some daemons that implement clean-up
599 jobs that are intended to be executed in
600 regular intervals benefit from timer-based
601 activation. In systemd, this is implemented
602 via
<filename>.timer
</filename> units, as
604 <citerefentry><refentrytitle>systemd.timer
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
608 <title>Other Forms of Activation
</title>
610 <para>Other forms of activation have been
611 suggested and implemented in some
612 systems. However, often there are simpler or
613 better alternatives, or they can be put
614 together of combinations of the schemes
615 above. Example: sometimes it appears useful to
616 start daemons or
<filename>.socket
</filename>
617 units when a specific IP address is configured
618 on a network interface, because network
619 sockets shall be bound to the
620 address. However, an alternative to implement
621 this is by utilizing the Linux IP_FREEBIND
622 socket option, as accessible via
623 <varname>FreeBind=yes
</varname> in systemd
625 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
626 for details). This option, when enabled,
627 allows sockets to be bound to a non-local, not
628 configured IP address, and hence allows
629 bindings to a particular IP address before it
630 actually becomes available, making such an
631 explicit dependency to the configured address
632 redundant. Another often suggested trigger for
633 service activation is low system
634 load. However, here too, a more convincing
635 approach might be to make proper use of
636 features of the operating system: in
637 particular, the CPU or IO scheduler of
638 Linux. Instead of scheduling jobs from
639 userspace based on monitoring the OS
640 scheduler, it is advisable to leave the
641 scheduling of processes to the OS scheduler
642 itself. systemd provides fine-grained access
643 to the CPU and IO schedulers. If a process
644 executed by the init system shall not
645 negatively impact the amount of CPU or IO
646 bandwith available to other processes, it
647 should be configured with
648 <varname>CPUSchedulingPolicy=idle
</varname>
650 <varname>IOSchedulingClass=idle
</varname>. Optionally,
651 this may be combined with timer-based
652 activation to schedule background jobs during
653 runtime and with minimal impact on the system,
654 and remove it from the boot phase
660 <title>Integration with Systemd
</title>
663 <title>Writing Systemd Unit Files
</title>
665 <para>When writing systemd unit files, it is
666 recommended to consider the following
670 <listitem><para>If possible do not use
671 the
<varname>Type=forking
</varname>
672 setting in service files. But if you
673 do, make sure to set the PID file path
674 using
<varname>PIDFile=
</varname>. See
675 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
676 for details.
</para></listitem>
678 <listitem><para>If your daemon
679 registers a D-Bus name on the bus,
681 <varname>Type=dbus
</varname> in the
683 possible.
</para></listitem>
685 <listitem><para>Make sure to set a
686 good human-readable description string
688 <varname>Description=
</varname>.
</para></listitem>
690 <listitem><para>Do not disable
691 <varname>DefaultDependencies=
</varname>,
692 unless you really know what you do and
693 your unit is involved in early boot or
694 late system shutdown.
</para></listitem>
696 <listitem><para>Normally, little if
697 any dependencies should need to
698 be defined explicitly. However, if you
699 do configure explicit dependencies, only refer to
701 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
702 or names introduced by your own
703 package to keep the unit file
705 system-independent.
</para></listitem>
707 <listitem><para>Since not all syslog
708 implementations are socket-activatable
709 yet, it is recommended to place an
710 <varname>After=syslog.target
</varname>
711 dependency in service files for
712 daemons that can log to
713 syslog.
<filename>syslog.target
</filename>
714 then either pulls in the syslog daemon
715 itself or simply the activation
716 socket. A
<varname>Wants=
</varname> or
717 even
<varname>Requires=
</varname>
718 dependency should generally not be
719 added, since it should be up to the
720 administrator whether he wants to
721 enable logging or not, and most syslog
722 clients work fine if no log daemon is
723 running.
</para></listitem>
725 <listitem><para>Make sure to include
726 an
<literal>[Install]
</literal>
727 section including installation
728 information for the unit file. See
729 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
730 for details. To activate your service
731 on boot make sure to add a
732 <varname>WantedBy=multi-user.target
</varname>
734 <varname>WantedBy=graphical.target
</varname>
735 directive. To activate your socket on
736 boot, make sure to add
737 <varname>WantedBy=sockets.target
</varname>. Usually
738 you also want to make sure that when
739 your service is installed your socket
740 is installed too, hence add
741 <varname>Also=foo.socket
</varname> in
743 <filename>foo.service
</filename>, for
744 a hypothetical program
745 <filename>foo
</filename>.
</para></listitem>
751 <title>Installing Systemd Service Files
</title>
753 <para>At the build installation time
754 (e.g.
<command>make install
</command> during
755 package build) packages are recommended to
756 install their systemd unit files in the
757 directory returned by
<command>pkg-config
759 --variable=systemdsystemunitdir
</command>
760 (for system services),
761 resp.
<command>pkg-config systemd
762 --variable=systemdsessionunitdir
</command>
763 (for session services). This will make the
764 services available in the system on explicit
765 request but not activate them automatically
766 during boot. Optionally, during package
767 installation (e.g.
<command>rpm -i
</command>
768 by the administrator) symlinks should be
769 created in the systemd configuration
771 <citerefentry><refentrytitle>systemd-install
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
772 tool, to activate them automatically on
776 <citerefentry><refentrytitle>autoconf
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
777 are recommended to use a configure script
778 excerpt like the following to determine the
779 unit installation path during source
780 configuration:
</para>
782 <programlisting>PKG_PROG_PKG_CONFIG
783 AC_ARG_WITH([systemdsystemunitdir],
784 AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
785 [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
786 AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
787 AM_CONDITIONAL(HAVE_SYSTEMD, [test -n
"$with_systemdsystemunitdir"])
</programlisting>
789 <para>This snippet allows automatic
790 installation of the unit files on systemd
791 machines, and optionally allows their
792 installation even on machines lacking
793 systemd. (Modification of this snippet for the
794 session unit directory is left as excercise to the
797 <para>Additionally, to ensure that
798 <command>make distcheck
</command> continues to
799 work, it is recommended to add the following
800 to the top-level
<filename>Makefile.am
</filename>
802 <citerefentry><refentrytitle>automake
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
805 <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
806 --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)
</programlisting>
808 <para>Finally, unit files should be installed in the system with an automake excerpt like the following:
</para>
810 <programlisting>if HAVE_SYSTEMD
811 systemdsystemunit_DATA = \
814 endif
</programlisting>
817 <citerefentry><refentrytitle>rpm
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
818 <filename>.spec
</filename> file use a snippet like
819 the following to enable/disable the service
820 during installation/deinstallation. Consult
821 the packaging guidelines of your distribution
822 for details and the equivalent for other
823 package managers:
</para>
825 <programlisting>%post
826 /usr/bin/systemd-install --realize enable foobar.service foobar.socket
>/dev/null
2>&1 || :
829 if [
"$1" -eq
0 ]; then
830 /usr/bin/systemd-install --realize disable foobar.service foobar.socket
>/dev/null
2>&1 || :
833 <para>Depending on whether your service should
834 or should not be started/stopped/restarted
835 during package installation, deinstallation or
836 upgrade, a different argument to
837 <option>--realize=
</option> may be
839 <citerefentry><refentrytitle>systemd-install
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
846 <title>Porting Existing Daemons
</title>
848 <para>Since new-style init systems such as systemd are
849 compatible with traditional SysV init systems it is
850 not strictly necessary to port existing daemons to the
851 new style. However doing so offers additional
852 functionality to the daemons as well as simplifying
853 integration into new-style init systems.
</para>
855 <para>To port an existing SysV compatible daemon the
856 following steps are recommended:
</para>
859 <listitem><para>If not already implemented,
860 add an optional command line switch to the
861 daemon to disable daemonization. This is
862 useful not only for using the daemon in
863 new-style init systems, but also to ease
864 debugging.
</para></listitem>
866 <listitem><para>If the daemon offers
867 interfaces to other software running on the
868 local system via local AF_UNIX sockets,
869 consider implementing socket-based activation
870 (see above). Usually a minimal patch is
871 sufficient to implement this: Extend the
872 socket creation in the daemon code so that
873 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
874 is checked for already passed sockets
875 first. If sockets are passed (i.e. when
876 <function>sd_listen_fds()
</function> returns a
877 positive value), skip the socket creation step
878 and use the passed sockets. Secondly, ensure
879 that the file-system socket nodes for local
880 AF_UNIX sockets used in the socket-based
881 activation are not removed when the daemon
882 shuts down, if sockets have been
883 passed. Third, if the daemon normally closes
884 all remaining open file descriptors as part of
885 its initialization, the sockets passed from
886 the init system must be spared. Since
887 new-style init systems guarantee that no
888 left-over file descriptors are passed to
889 executed processes, it might be a good choice
890 to simply skip the closing of all remaining
891 open file descriptors if sockets are
892 passed.
</para></listitem>
894 <listitem><para>Write and install a systemd
895 unit file for the service (and the sockets if
896 socket-based activation is used, as well as a
897 path unit file, if the daemon processes a
898 spool directory), see above for
899 details.
</para></listitem>
901 <listitem><para>If the daemon exposes
902 interfaces via D-Bus, write and install a
903 D-Bus activation file for the service, see
904 above for details.
</para></listitem>
909 <title>See Also
</title>
911 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
912 <citerefentry><refentrytitle>systemd-install
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
913 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
914 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
915 <citerefentry><refentrytitle>sd_notify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
916 <citerefentry><refentrytitle>daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
917 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
projects / thirdparty / systemd.git / blob