From 64aba792f7d2af56ba5308518a270490f85f3b8b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 22 Jun 2010 02:42:10 +0200 Subject: [PATCH] man: add initial version of daemon(7) --- Makefile.am | 9 +- man/daemon.xml | 316 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 322 insertions(+), 3 deletions(-) create mode 100644 man/daemon.xml diff --git a/Makefile.am b/Makefile.am index 6cdacbe0..fcc3287c 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 00000000..3d1e921a --- /dev/null +++ b/man/daemon.xml @@ -0,0 +1,316 @@ + + + + + + + + + daemon + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + daemon + 7 + + + + daemon + Writing and Packaging System Daemons + + + + Description + + 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. + + + SysV Daemons + + 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. + + + 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 + /proc/self/fd, + with a fallback of iterating from file + descriptor 3 to the value returned by + getrlimit() for + RLIMIT_NOFILE. + + 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. + + Reset the signal mask + using sigprocmask(). + + Call fork(), + to create a background + process. + + In the child, call + setsid() to detach from any terminal + and create an independent + session. + + In the child, call + fork() again, to ensure the daemon can + never re-aquire a terminal + again. + + 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. + + In the daemon process, + connect /dev/null + to STDIN, STDOUT, + STDERR. + + 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. + + 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. + + In the daemon process, + drop privileges, if possible and + applicable. + + 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. + + 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. + + + The BSD daemon() function should not be + used, as it does only a subset of these steps. + + 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. + + + + New-Style Daemons + + 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. + + 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. + + It is recommended for new-style daemons + to implement the following: + + + If SIGTERM is + received, shut down the daemon and + exit cleanly. + + If SIGHUP is received, + reload the configuration files, if + this applies. + + 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). + + 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. + + 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. + + 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. + + 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. + + If applicable a daemon + should notify the init system about + startup completion or status + updates via the sd_notify() + interface. + + 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. + + + + + + Bus Activation + + + + Socket Activation + + + + Writing Service Files + + + + Installing Service Files + + + + + + + See Also + + daemon3, + sd_listen_fds3 + + + + -- 2.39.5