daemon.xml revision 436c44a5d64ef136ead64e9b03c8c05cc573a61b
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok This file is part of systemd.
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok Copyright 2010 Lennart Poettering
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok systemd is free software; you can redistribute it and/or modify it
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok under the terms of the GNU General Public License as published by
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok the Free Software Foundation; either version 2 of the License, or
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas (at your option) any later version.
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok systemd is distributed in the hope that it will be useful, but
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok WITHOUT ANY WARRANTY; without even the implied warranty of
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok General Public License for more details.
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok You should have received a copy of the GNU General Public License
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok along with systemd; If not, see <http://www.gnu.org/licenses/>.
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refentryinfo>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok </authorgroup>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok </refentryinfo>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refnamediv>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refpurpose>Writing and Packaging System Daemons</refpurpose>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok </refnamediv>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <para>A daemon is a service process that runs in the
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok background and supervises the system or provides
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok functionality to other processes. Traditionally,
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok daemons are implemented following a scheme originating
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok in SysV Unix. Modern daemons should follow a simpler
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek yet more powerful scheme here called "new-style"
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek daemons, as implemented by systemd. </para>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <para>When a traditional SysV daemon
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek starts, it should execute the following steps
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek as part of the initialization. Note that these
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek steps are unnecessary for new-style daemons,
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek and should only be implemented if compatibility
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek with SysV is essential.</para>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <listitem><para>Close all open file
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek descriptors except STDIN, STDOUT,
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek STDERR (i.e. the first three file
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek descriptors 0, 1, 2). This ensures
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek that no accidentally passed file
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek descriptor stays around in the daemon
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek process. On Linux this is best
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek implemented by iterating through
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <filename>/proc/self/fd</filename>,
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek with a fallback of iterating from file
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek descriptor 3 to the value returned by
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek RLIMIT_NOFILE.</para></listitem>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <listitem><para>Reset all signal
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek handlers to their default. This is
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek best done by iterating through the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek available signals up to the limit of
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek _NSIG and resetting them to
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <listitem><para>Reset the signal mask
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek using sigprocmask().</para></listitem>
e7ecdfc15cee7a90da23d89c228ada5560ebb3a4Zbigniew Jędrzejewski-Szmek to create a background
e7ecdfc15cee7a90da23d89c228ada5560ebb3a4Zbigniew Jędrzejewski-Szmek <listitem><para>In the child, call
e7ecdfc15cee7a90da23d89c228ada5560ebb3a4Zbigniew Jędrzejewski-Szmek setsid() to detach from any terminal
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek and create an independent
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok fork() again, to ensure the daemon can
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok never re-aquire a terminal
ccc9a4f9ffdab069b0b785627c48962fdadf6d46Zbigniew Jędrzejewski-Szmek first child, so that only the second
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok child (the actual daemon process)
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok stays around. This ensures that the
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas daemon process is reparented to
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek init/PID 1, as all daemons should
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <listitem><para>In the daemon process,
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek connect <filename>/dev/null</filename>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek to STDIN, STDOUT,
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas reset the umask to 0, so that the file
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek modes passed to open(), mkdir() and
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek suchlike directly control the access
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek mode of the created files and
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <listitem><para>In the daemon process,
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek change the current directory to the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek root directory (/), in order to avoid
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek that the daemon involuntarily
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek blocks mount points from being
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok drop privileges, if possible and
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek process notify the original process
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek started that initialization is
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek complete. This can be implemented via
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek an unnamed pipe or similar
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek communication channel that is created
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas before the first fork() and available
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas original process. The process that
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas invoked the daemon must be able to
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek rely that this exit() happens after
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek initialization is complete and all
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek external communication channels
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas <para>The BSD daemon() function should not be
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas used, as it does only a subset of these steps.</para>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <para>A daemon that needs to provide
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek compatibility with SysV systems should
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek implement the scheme pointed out
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek above. However, it is recommended to make this
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas behaviour optional and configurable via a
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas command line argument, to ease debugging as
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas well as to simplify integration into systems
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas using systemd.</para>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <para>Modern services for Linux should be
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas implemented as new-style daemons. This makes it
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek easier to supervise and control them at
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas runtime and simplifies their
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas implementation.</para>
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas <para>For developing a new-style daemon none
6d2679917919f1d59bf677d719fb84aedf8b9558Zbigniew Jędrzejewski-Szmek of the initialization steps recommended for
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek SysV daemons need to be implemented. New-style
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas init systems such as systemd make all of them
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas redundant. Moreover, since some of these steps
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas interfere with process monitoring, file
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek descriptor passing and other functionality of
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas the init system it is recommended not to
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas execute them when run as new-style
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas service.</para>
78da2cd926937935741ce86bd53c8b546cca6f7aHarald Hoyer <para>It is recommended for new-style daemons
78da2cd926937935741ce86bd53c8b546cca6f7aHarald Hoyer to implement the following:</para>
78da2cd926937935741ce86bd53c8b546cca6f7aHarald Hoyer <orderedlist>
78da2cd926937935741ce86bd53c8b546cca6f7aHarald Hoyer received, shut down the daemon and
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek reload the configuration files, if
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas code from the main daemon process, as
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas this is used by the init system to
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas detect service errors and problems. It
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas is recommended to follow the exit code
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek scheme as defined in LSB
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek recommendations for SysV init scripts
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek (http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html).</para></listitem>
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas rely on systemd's functionality to
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas limit the access of the daemon to
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas files, services and other
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas resources. i.e. rely on systemd's
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas resource limit control instead of
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek implementing your own, rely on
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek systemd's privilege dropping code
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek instead of implementing it in the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek daemon, and similar.</para></listitem>
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas applicable expose the daemon's control
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas interface via the D-Bus IPC system and
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas grab a bus name as last step of
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas your daemon bus-activatable, via
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas supplying a D-Bus service activation
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas configuration file. This has multiple
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas advantages: your daemon may be started
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek lazily on-demand; it may be started in
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas parallel to other daemons requiring it
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas -- which maximizes parallelization and
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas boot-up speed; your daemon can be
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas restarted on failure, without losing
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas any bus requests, as the bus queues
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas requests for activatable
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas provides services to other local
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas processes or remote clients via a
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas socket, it should be made
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas socket-activatable following the
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas scheme pointed out below. Like D-Bus
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok activation this enables on-demand
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok starting of services as well as it
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok allows improved parallelization of
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok service start-up. Also, for state-less
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok protocols (such as syslog, DNS) a
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek daemon implementing socket-based
1959c6ce940786d33f91e19c41441bf4c9f6a768Thomas Hindoe Paaboel Andersen activation can be restarted without
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok losing a single
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas should notify the init system about
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas startup completion or status
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas updates via the sd_notify()
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <listitem><para>Instead of using the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek syslog() call to log directly to the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek system logger, a new-style daemon may
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas choose to simply log to STDERR via
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas fprintf(), which is then forwarded to
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas syslog by the init system. If log
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas priorities are necessary these can be
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas encoded by prefixing individual log
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas lines with strings like "<4>"
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas (for log priority 4 "WARNING" in the
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas syslog priority scheme), following a
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas similar style as the Linux kernel's
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas printk() priority system. In fact, using
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas this style of logging also enables the
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas init system to optionally direct all
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas application logging to the kernel log
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas buffer (kmsg), as accessible via
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas </orderedlist>
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
c3fec6715df4df7bfec9a0d0315e8f17b53eeb8eWilliam Giokas <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok </refsect1>