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