1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU General Public License as published by
12 the Free Software Foundation; either version 2 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 General Public License for more details.
20 You should have received a copy of the GNU General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemd.special">
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>daemon</refentrytitle>
42 <manvolnum>7</manvolnum>
46 <refname>daemon</refname>
47 <refpurpose>Writing and Packaging System Daemons</refpurpose>
51 <title>Description</title>
53 <para>A daemon is a service process that runs in the
54 background and supervises the system or provides
55 functionality to other processes. Traditionally,
56 daemons are implemented following a scheme originating
57 in SysV Unix. Modern daemons should follow a simpler
58 yet more powerful scheme here called "new-style"
59 daemons, as implemented by systemd. </para>
62 <title>SysV Daemons</title>
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,
68 and should only be implemented if compatbility
69 with SysV is essential.</para>
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
84 RLIMIT_NOFILE.</para></listitem>
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>
93 <listitem><para>Reset the signal mask
94 using sigprocmask().</para></listitem>
96 <listitem><para>Call fork(),
97 to create a background
98 process.</para></listitem>
100 <listitem><para>In the child, call
101 setsid() to detach from any terminal
102 and create an independent
103 session.</para></listitem>
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>
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>
118 <listitem><para>In the daemon process,
119 connect <filename>/dev/null</filename>
121 STDERR.</para></listitem>
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>
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>
137 <listitem><para>In the daemon process,
138 drop privileges, if possible and
139 applicable.</para></listitem>
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>
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
157 accessible.</para></listitem>
160 <para>The BSD daemon() function should not be
161 used, as it does only a subset of these steps.</para>
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>
174 <title>New-Style Daemons</title>
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>
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
193 <para>It is recommended for new-style daemons
194 to implement the following:</para>
197 <listitem><para>If SIGTERM is
198 received, shut down the daemon and
199 exit cleanly.</para></listitem>
201 <listitem><para>If SIGHUP is received,
202 reload the configuration files, if
203 this applies.</para></listitem>
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>
214 <listitem><para>As much as possible,
215 rely on systemd's functionality to
216 limit the accces of the daemon to
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>
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>
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>
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
253 allows improved parallization of
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
259 request.</para></listitem>
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>
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>
290 <title>Bus Activation</title>
294 <title>Socket Activation</title>
298 <title>Writing Service Files</title>
302 <title>Installing Service Files</title>
309 <title>See Also</title>
311 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
312 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>