diff options
| -rw-r--r-- | Makefile.am | 9 | ||||
| -rw-r--r-- | man/daemon.xml | 316 |
2 files changed, 322 insertions, 3 deletions
diff --git a/Makefile.am b/Makefile.am index 6cdacbe02b..fcc3287c59 100644 --- a/Makefile.am +++ b/Makefile.am @@ -307,14 +307,16 @@ EXTRA_DIST += \ dist_man_MANS = \ man/systemd.unit.5 \ - man/systemd.service.5 + man/systemd.service.5 \ + man/daemon.7 nodist_man_MANS = \ man/systemd.special.7 dist_noinst_DATA = \ man/systemd.unit.html \ - man/systemd.service.html + man/systemd.service.html \ + man/daemon.html nodist_noinst_DATA = \ man/systemd.special.html @@ -324,7 +326,8 @@ EXTRA_DIST += \ man/systemd.service.xml \ man/systemd.special.xml.in \ man/systemd.special.7.in \ - man/systemd.special.html.in + man/systemd.special.html.in \ + man/daemon.xml systemd_SOURCES = \ src/main.c diff --git a/man/daemon.xml b/man/daemon.xml new file mode 100644 index 0000000000..3d1e921a16 --- /dev/null +++ b/man/daemon.xml @@ -0,0 +1,316 @@ +<?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 compatbility + 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 accces 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 parallization 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 "<4>" + (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>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |