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