]>
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 | |
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. | |
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 | |
18 | General Public License for more details. | |
19 | ||
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/>. | |
22 | --> | |
23 | ||
24 | <refentry id="systemd.special"> | |
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> | |
47 | <refpurpose>Writing and Packaging System Daemons</refpurpose> | |
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 | |
58 | yet more powerful scheme here called "new-style" | |
59 | daemons, as implemented by systemd. </para> | |
60 | ||
61 | <refsect2> | |
62 | <title>SysV Daemons</title> | |
63 | ||
64 | <para>When a traditional SysV daemon | |
65 | starts, it should execute the following steps | |
66 | as part of the initialization. Note that these | |
67 | steps are unnecessary for new-style daemons, | |
436c44a5 | 68 | and should only be implemented if compatibility |
64aba792 LP |
69 | with SysV is essential.</para> |
70 | ||
71 | <orderedlist> | |
72 | <listitem><para>Close all open file | |
73 | descriptors except STDIN, STDOUT, | |
74 | STDERR (i.e. the first three file | |
75 | descriptors 0, 1, 2). This ensures | |
76 | that no accidentally passed file | |
77 | descriptor stays around in the daemon | |
78 | process. On Linux this is best | |
79 | implemented by iterating through | |
80 | <filename>/proc/self/fd</filename>, | |
81 | with a fallback of iterating from file | |
82 | descriptor 3 to the value returned by | |
83 | getrlimit() for | |
84 | RLIMIT_NOFILE.</para></listitem> | |
85 | ||
86 | <listitem><para>Reset all signal | |
87 | handlers to their default. This is | |
88 | best done by iterating through the | |
89 | available signals up to the limit of | |
90 | _NSIG and resetting them to | |
91 | SIG_DFL.</para></listitem> | |
92 | ||
93 | <listitem><para>Reset the signal mask | |
94 | using sigprocmask().</para></listitem> | |
95 | ||
96 | <listitem><para>Call fork(), | |
97 | to create a background | |
98 | process.</para></listitem> | |
99 | ||
100 | <listitem><para>In the child, call | |
101 | setsid() to detach from any terminal | |
102 | and create an independent | |
103 | session.</para></listitem> | |
104 | ||
105 | <listitem><para>In the child, call | |
106 | fork() again, to ensure the daemon can | |
107 | never re-aquire a terminal | |
108 | again.</para></listitem> | |
109 | ||
110 | <listitem><para>Call exit() in the | |
111 | first child, so that only the second | |
112 | child (the actual daemon process) | |
113 | stays around. This ensures that the | |
114 | daemon process is reparented to | |
115 | init/PID 1, as all daemons should | |
116 | be.</para></listitem> | |
117 | ||
118 | <listitem><para>In the daemon process, | |
119 | connect <filename>/dev/null</filename> | |
120 | to STDIN, STDOUT, | |
121 | STDERR.</para></listitem> | |
122 | ||
123 | <listitem><para>In the daemon process, | |
124 | reset the umask to 0, so that the file | |
125 | modes passed to open(), mkdir() and | |
126 | suchlike directly control the access | |
127 | mode of the created files and | |
128 | directories.</para></listitem> | |
129 | ||
130 | <listitem><para>In the daemon process, | |
131 | change the current directory to the | |
132 | root directory (/), in order to avoid | |
133 | that the daemon involuntarily | |
134 | blocks mount points from being | |
135 | unmounted.</para></listitem> | |
136 | ||
137 | <listitem><para>In the daemon process, | |
138 | drop privileges, if possible and | |
139 | applicable.</para></listitem> | |
140 | ||
141 | <listitem><para>From the daemon | |
142 | process notify the original process | |
143 | started that initialization is | |
144 | complete. This can be implemented via | |
145 | an unnamed pipe or similar | |
146 | communication channel that is created | |
147 | before the first fork() and available | |
148 | in both processes.</para></listitem> | |
149 | ||
150 | <listitem><para>Call exit() in the | |
151 | original process. The process that | |
152 | invoked the daemon must be able to | |
153 | rely that this exit() happens after | |
154 | initialization is complete and all | |
155 | external communication channels | |
156 | established and | |
157 | accessible.</para></listitem> | |
158 | </orderedlist> | |
159 | ||
160 | <para>The BSD daemon() function should not be | |
161 | used, as it does only a subset of these steps.</para> | |
162 | ||
163 | <para>A daemon that needs to provide | |
164 | compatibility with SysV systems should | |
165 | implement the scheme pointed out | |
166 | above. However, it is recommended to make this | |
167 | behaviour optional and configurable via a | |
168 | command line argument, to ease debugging as | |
169 | well as to simplify integration into systems | |
170 | using systemd.</para> | |
171 | </refsect2> | |
172 | ||
173 | <refsect2> | |
174 | <title>New-Style Daemons</title> | |
175 | ||
176 | <para>Modern services for Linux should be | |
177 | implemented as new-style daemons. This makes it | |
178 | easier to supervise and control them at | |
179 | runtime and simplifies their | |
180 | implementation.</para> | |
181 | ||
182 | <para>For developing a new-style daemon none | |
183 | of the initialization steps recommended for | |
184 | SysV daemons need to be implemented. New-style | |
185 | init systems such as systemd make all of them | |
186 | redundant. Moreover, since some of these steps | |
187 | interfere with process monitoring, file | |
188 | descriptor passing and other functionality of | |
189 | the init system it is recommended not to | |
190 | execute them when run as new-style | |
191 | service.</para> | |
192 | ||
193 | <para>It is recommended for new-style daemons | |
194 | to implement the following:</para> | |
195 | ||
196 | <orderedlist> | |
197 | <listitem><para>If SIGTERM is | |
198 | received, shut down the daemon and | |
199 | exit cleanly.</para></listitem> | |
200 | ||
201 | <listitem><para>If SIGHUP is received, | |
202 | reload the configuration files, if | |
203 | this applies.</para></listitem> | |
204 | ||
205 | <listitem><para>Provide a correct exit | |
206 | code from the main daemon process, as | |
207 | this is used by the init system to | |
208 | detect service errors and problems. It | |
209 | is recommended to follow the exit code | |
210 | scheme as defined in LSB | |
211 | recommendations for SysV init scripts | |
212 | (http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html).</para></listitem> | |
213 | ||
214 | <listitem><para>As much as possible, | |
215 | rely on systemd's functionality to | |
436c44a5 | 216 | limit the access of the daemon to |
64aba792 LP |
217 | files, services and other |
218 | resources. i.e. rely on systemd's | |
219 | resource limit control instead of | |
220 | implementing your own, rely on | |
221 | systemd's privilege dropping code | |
222 | instead of implementing it in the | |
223 | daemon, and similar.</para></listitem> | |
224 | ||
225 | <listitem><para>If possible and | |
226 | applicable expose the daemon's control | |
227 | interface via the D-Bus IPC system and | |
228 | grab a bus name as last step of | |
229 | initialization.</para></listitem> | |
230 | ||
231 | <listitem><para>If D-Bus is used, make | |
232 | your daemon bus-activatable, via | |
233 | supplying a D-Bus service activation | |
234 | configuration file. This has multiple | |
235 | advantages: your daemon may be started | |
236 | lazily on-demand; it may be started in | |
237 | parallel to other daemons requiring it | |
238 | -- which maximizes parallelization and | |
239 | boot-up speed; your daemon can be | |
240 | restarted on failure, without losing | |
241 | any bus requests, as the bus queues | |
242 | requests for activatable | |
243 | services.</para></listitem> | |
244 | ||
245 | <listitem><para>If your daemon | |
246 | provides services to other local | |
247 | processes or remote clients via a | |
248 | socket, it should be made | |
249 | socket-activatable following the | |
250 | scheme pointed out below. Like D-Bus | |
251 | activation this enables on-demand | |
252 | starting of services as well as it | |
436c44a5 | 253 | allows improved parallelization of |
64aba792 LP |
254 | service start-up. Also, for state-less |
255 | protocols (such as syslog, DNS) a | |
256 | daemon implementing socket-based | |
257 | activation can be restarted without | |
258 | losing a single | |
259 | request.</para></listitem> | |
260 | ||
261 | <listitem><para>If applicable a daemon | |
262 | should notify the init system about | |
263 | startup completion or status | |
264 | updates via the sd_notify() | |
265 | interface.</para></listitem> | |
266 | ||
267 | <listitem><para>Instead of using the | |
268 | syslog() call to log directly to the | |
269 | system logger, a new-style daemon may | |
270 | choose to simply log to STDERR via | |
271 | fprintf(), which is then forwarded to | |
272 | syslog by the init system. If log | |
273 | priorities are necessary these can be | |
274 | encoded by prefixing individual log | |
275 | lines with strings like "<4>" | |
276 | (for log priority 4 "WARNING" in the | |
277 | syslog priority scheme), following a | |
278 | similar style as the Linux kernel's | |
279 | printk() priority system. In fact, using | |
280 | this style of logging also enables the | |
281 | init system to optionally direct all | |
282 | application logging to the kernel log | |
283 | buffer (kmsg), as accessible via | |
284 | dmesg.</para></listitem> | |
285 | ||
286 | </orderedlist> | |
287 | </refsect2> | |
288 | ||
289 | <refsect2> | |
290 | <title>Bus Activation</title> | |
291 | </refsect2> | |
292 | ||
293 | <refsect2> | |
294 | <title>Socket Activation</title> | |
295 | </refsect2> | |
296 | ||
297 | <refsect2> | |
298 | <title>Writing Service Files</title> | |
299 | </refsect2> | |
300 | ||
301 | <refsect2> | |
302 | <title>Installing Service Files</title> | |
303 | </refsect2> | |
304 | ||
305 | </refsect1> | |
306 | ||
307 | ||
308 | <refsect1> | |
160cd5c9 LP |
309 | <title>See Also</title> |
310 | <para> | |
311 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
312 | <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
313 | <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
314 | </para> | |
64aba792 LP |
315 | </refsect1> |
316 | ||
317 | </refentry> |