[thirdparty/systemd.git] / man / daemon.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd.special">

        <refentryinfo>
                <title>daemon</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>daemon</refentrytitle>
                <manvolnum>7</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>daemon</refname>
                <refpurpose>Writing and Packaging System Daemons</refpurpose>
        </refnamediv>

        <refsect1>
                <title>Description</title>

                <para>A daemon is a service process that runs in the
                background and supervises the system or provides
                functionality to other processes. Traditionally,
                daemons are implemented following a scheme originating
                in SysV Unix. Modern daemons should follow a simpler
                yet more powerful scheme here called "new-style"
                daemons, as implemented by systemd. </para>

                <refsect2>
                        <title>SysV Daemons</title>

                        <para>When a traditional SysV daemon
                        starts, it should execute the following steps
                        as part of the initialization. Note that these
                        steps are unnecessary for new-style daemons,
                        and should only be implemented if compatibility
                        with SysV is essential.</para>

                        <orderedlist>
                                <listitem><para>Close all open file
                                descriptors except STDIN, STDOUT,
                                STDERR (i.e. the first three file
                                descriptors 0, 1, 2). This ensures
                                that no accidentally passed file
                                descriptor stays around in the daemon
                                process. On Linux this is best
                                implemented by iterating through
                                <filename>/proc/self/fd</filename>,
                                with a fallback of iterating from file
                                descriptor 3 to the value returned by
                                getrlimit() for
                                RLIMIT_NOFILE.</para></listitem>

                                <listitem><para>Reset all signal
                                handlers to their default. This is
                                best done by iterating through the
                                available signals up to the limit of
                                _NSIG and resetting them to
                                SIG_DFL.</para></listitem>

                                <listitem><para>Reset the signal mask
                                using sigprocmask().</para></listitem>

                                <listitem><para>Call fork(),
                                to create a background
                                process.</para></listitem>

                                <listitem><para>In the child, call
                                setsid() to detach from any terminal
                                and create an independent
                                session.</para></listitem>

                                <listitem><para>In the child, call
                                fork() again, to ensure the daemon can
                                never re-aquire a terminal
                                again.</para></listitem>

                                <listitem><para>Call exit() in the
                                first child, so that only the second
                                child (the actual daemon process)
                                stays around. This ensures that the
                                daemon process is reparented to
                                init/PID 1, as all daemons should
                                be.</para></listitem>

                                <listitem><para>In the daemon process,
                                connect <filename>/dev/null</filename>
                                to STDIN, STDOUT,
                                STDERR.</para></listitem>

                                <listitem><para>In the daemon process,
                                reset the umask to 0, so that the file
                                modes passed to open(), mkdir() and
                                suchlike directly control the access
                                mode of the created files and
                                directories.</para></listitem>

                                <listitem><para>In the daemon process,
                                change the current directory to the
                                root directory (/), in order to avoid
                                that the daemon involuntarily
                                blocks mount points from being
                                unmounted.</para></listitem>

                                <listitem><para>In the daemon process,
                                drop privileges, if possible and
                                applicable.</para></listitem>

                                <listitem><para>From the daemon
                                process notify the original process
                                started that initialization is
                                complete. This can be implemented via
                                an unnamed pipe or similar
                                communication channel that is created
                                before the first fork() and available
                                in both processes.</para></listitem>

                                <listitem><para>Call exit() in the
                                original process. The process that
                                invoked the daemon must be able to
                                rely that this exit() happens after
                                initialization is complete and all
                                external communication channels
                                established and
                                accessible.</para></listitem>
                        </orderedlist>

                        <para>The BSD daemon() function should not be
                        used, as it does only a subset of these steps.</para>

                        <para>A daemon that needs to provide
                        compatibility with SysV systems should
                        implement the scheme pointed out
                        above. However, it is recommended to make this
                        behaviour optional and configurable via a
                        command line argument, to ease debugging as
                        well as to simplify integration into systems
                        using systemd.</para>
                </refsect2>

                <refsect2>
                        <title>New-Style Daemons</title>

                        <para>Modern services for Linux should be
                        implemented as new-style daemons. This makes it
                        easier to supervise and control them at
                        runtime and simplifies their
                        implementation.</para>

                        <para>For developing a new-style daemon none
                        of the initialization steps recommended for
                        SysV daemons need to be implemented. New-style
                        init systems such as systemd make all of them
                        redundant. Moreover, since some of these steps
                        interfere with process monitoring, file
                        descriptor passing and other functionality of
                        the init system it is recommended not to
                        execute them when run as new-style
                        service.</para>

                        <para>It is recommended for new-style daemons
                        to implement the following:</para>

                        <orderedlist>
                                <listitem><para>If SIGTERM is
                                received, shut down the daemon and
                                exit cleanly.</para></listitem>

                                <listitem><para>If SIGHUP is received,
                                reload the configuration files, if
                                this applies.</para></listitem>

                                <listitem><para>Provide a correct exit
                                code from the main daemon process, as
                                this is used by the init system to
                                detect service errors and problems. It
                                is recommended to follow the exit code
                                scheme as defined in LSB
                                recommendations for SysV init scripts
                                (http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html).</para></listitem>

                                <listitem><para>As much as possible,
                                rely on systemd's functionality to
                                limit the access of the daemon to
                                files, services and other
                                resources. i.e. rely on systemd's
                                resource limit control instead of
                                implementing your own, rely on
                                systemd's privilege dropping code
                                instead of implementing it in the
                                daemon, and similar.</para></listitem>

                                <listitem><para>If possible and
                                applicable expose the daemon's control
                                interface via the D-Bus IPC system and
                                grab a bus name as last step of
                                initialization.</para></listitem>

                                <listitem><para>If D-Bus is used, make
                                your daemon bus-activatable, via
                                supplying a D-Bus service activation
                                configuration file. This has multiple
                                advantages: your daemon may be started
                                lazily on-demand; it may be started in
                                parallel to other daemons requiring it
                                -- which maximizes parallelization and
                                boot-up speed; your daemon can be
                                restarted on failure, without losing
                                any bus requests, as the bus queues
                                requests for activatable
                                services.</para></listitem>

                                <listitem><para>If your daemon
                                provides services to other local
                                processes or remote clients via a
                                socket, it should be made
                                socket-activatable following the
                                scheme pointed out below. Like D-Bus
                                activation this enables on-demand
                                starting of services as well as it
                                allows improved parallelization of
                                service start-up. Also, for state-less
                                protocols (such as syslog, DNS) a
                                daemon implementing socket-based
                                activation can be restarted without
                                losing a single
                                request.</para></listitem>

                                <listitem><para>If applicable a daemon
                                should notify the init system about
                                startup completion or status
                                updates via the sd_notify()
                                interface.</para></listitem>

                                <listitem><para>Instead of using the
                                syslog() call to log directly to the
                                system logger, a new-style daemon may
                                choose to simply log to STDERR via
                                fprintf(), which is then forwarded to
                                syslog by the init system. If log
                                priorities are necessary these can be
                                encoded by prefixing individual log
                                lines with strings like "&lt;4&gt;"
                                (for log priority 4 "WARNING" in the
                                syslog priority scheme), following a
                                similar style as the Linux kernel's
                                printk() priority system. In fact, using
                                this style of logging also enables the
                                init system to optionally direct all
                                application logging to the kernel log
                                buffer (kmsg), as accessible via
                                dmesg.</para></listitem>

                        </orderedlist>
                </refsect2>

                <refsect2>
                        <title>Bus Activation</title>
                </refsect2>

                <refsect2>
                        <title>Socket Activation</title>
                </refsect2>

                <refsect2>
                        <title>Writing Service Files</title>
                </refsect2>

                <refsect2>
                        <title>Installing Service Files</title>
                </refsect2>

        </refsect1>


        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>
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>