X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fdaemon.xml;h=007ec95b97e96a82bba5980c8f98138494dbe184;hp=3d1e921a165c36fd594bfe726b94f6f7674d8a12;hb=6908d3842a3b69b90106646a16f51a6b089026bd;hpb=64aba792f7d2af56ba5308518a270490f85f3b8b diff --git a/man/daemon.xml b/man/daemon.xml index 3d1e921a1..007ec95b9 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + daemon @@ -55,8 +55,12 @@ 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. + yet more powerful scheme (here called "new-style" + daemons), as implemented by + systemd1. This + manual page covers both schemes, and in + particular includes recommendations for daemons that + shall be included in the systemd init system. SysV Daemons @@ -64,8 +68,8 @@ 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 + steps are unnecessary for new-style daemons (see below), + and should only be implemented if compatibility with SysV is essential. @@ -80,7 +84,7 @@ /proc/self/fd, with a fallback of iterating from file descriptor 3 to the value returned by - getrlimit() for + getrlimit() for RLIMIT_NOFILE. Reset all signal @@ -91,23 +95,30 @@ SIG_DFL. Reset the signal mask - using sigprocmask(). + using + sigprocmask(). - Call fork(), + Sanitize the + environment block, removing or + resetting environment variables that + might negatively impact daemon + runtime. + + Call fork(), to create a background process. In the child, call - setsid() to detach from any terminal - and create an independent - session. + 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. + fork() again, to + ensure the daemon can never re-aquire + a terminal again. - Call exit() in the + Call exit() in the first child, so that only the second child (the actual daemon process) stays around. This ensures that the @@ -122,7 +133,7 @@ In the daemon process, reset the umask to 0, so that the file - modes passed to open(), mkdir() and + modes passed to open(), mkdir() and suchlike directly control the access mode of the created files and directories. @@ -134,6 +145,23 @@ blocks mount points from being unmounted. + In the daemon process, + write the daemon PID (as returned by + getpid()) to a + PID file, for example + /var/run/foobar.pid + (for a hypothetical daemon "foobar"), + to ensure that the daemon cannot be + started more than once. This must be + implemented in race-free fashion so + that the PID file is only updated when + at the same time it is verified that + the PID previously stored in the PID + file no longer exists or belongs to a + foreign process. Commonly some kind of + file locking is employed to implement + this logic. + In the daemon process, drop privileges, if possible and applicable. @@ -144,21 +172,25 @@ 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. + before the first + fork() and hence + available in both the original and the + daemon process. - Call exit() in the + 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 + 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. + The BSD daemon() function should not be + used, as it implements only a subset of these steps. A daemon that needs to provide compatibility with SysV systems should @@ -190,6 +222,17 @@ execute them when run as new-style service. + Note that new-style init systems + guarantee execution of daemon processes in + clean process contexts: it is guaranteed that + the environment block is sanitized, that the + signal handlers and mask is reset and that no + left-over file descriptors are passed. Daemons + will be executed in their own session, and + STDIN/STDOUT/STDERR connected to + /dev/null unless + otherwise configured. The umask is reset. + It is recommended for new-style daemons to implement the following: @@ -207,20 +250,10 @@ 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. + scheme as defined in the LSB + recommendations for SysV init + scripts. If possible and applicable expose the daemon's control @@ -228,6 +261,29 @@ grab a bus name as last step of initialization. + For integration in + systemd, provide a + .service unit + file that carries information about + starting, stopping and otherwise + maintaining the daemon. See + systemd.service5 + for details. + + As much as possible, + rely on the init systemd's + functionality to limit the access of + the daemon to files, services and + other resources. i.e. in the case of + systemd, 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. See + systemd.exec5 + for the available + controls. + If D-Bus is used, make your daemon bus-activatable, via supplying a D-Bus service activation @@ -239,8 +295,8 @@ boot-up speed; your daemon can be restarted on failure, without losing any bus requests, as the bus queues - requests for activatable - services. + requests for activatable services. See + below for details. If your daemon provides services to other local @@ -250,25 +306,26 @@ scheme pointed out below. Like D-Bus activation this enables on-demand starting of services as well as it - allows improved parallization of + 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. + losing a single request. See below for + details. If applicable a daemon should notify the init system about - startup completion or status - updates via the sd_notify() + startup completion or status updates + via the + sd_notify3 interface. Instead of using the - syslog() call to log directly to 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 + fprintf(), which is then forwarded to syslog by the init system. If log priorities are necessary these can be encoded by prefixing individual log @@ -276,41 +333,629 @@ (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. + 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 + dmesg1. This + kind of logging may be enabled by + setting + StandardError=syslog + in the service unit file. For details + see + sd-daemon7 + and + systemd.exec5. + + These recommendations are similar but + not identical to the Apple + MacOS X Daemon Requirements. + + + + + Activation + + New-style init systems provide multiple + additional mechanisms to activate services, as + detailed below. It is common that services are + configured to be activated via more than one mechanism + at the same time. An example for systemd: + bluetoothd.service might get + activated either when Bluetooth hardware is plugged + in, or when an application accesses its programming + interfaces via D-Bus. Or, a print server daemon might + get activated when traffic arrives at an IPP port, or + when a printer is plugged in, or when a file is queued + in the printer spool directory. Even for services that + are intended to be started on system bootup + unconditionally it is a good idea to implement some of + the various activation schemes outlined below, in + order to maximize parallelization: if a daemon + implements a D-Bus service or listening socket, + implementing the full bus and socket activation scheme + allows starting of the daemon with its clients in + parallel (which speeds up boot-up), since all its + communication channels are established already, and no + request is lost because client requests will be queued + by the bus system (in case of D-Bus) or the kernel (in + case of sockets), until the activation is + completed. + + + Activation on Boot + + Old-style daemons are usually activated + exclusively on boot (and manually by the + administrator) via SysV init scripts, as + detailed in the LSB + Linux Standard Base Core + Specification. This method of + activation is supported ubiquitiously on Linux + init systems, both old-style and new-style + systems. Among other issues SysV init scripts + have the disadvantage of involving shell + scripts in the boot process. New-style init + systems generally employ updated versions of + activation, both during boot-up and during + runtime and using more minimal service + description files. + + In systemd, if the developer or + administrator wants to make sure a service or + other unit is activated automatically on boot + it is recommended to place a symlink to the + unit file in the .wants/ + directory of either + multi-user.target or + graphical.target, which + are normally used as boot targets at system + startup. See + systemd.unit5 + for details about the + .wants/ directories, and + systemd.special7 + for details about the two boot targets. + + + + + Socket-Based Activation + + In order to maximize the possible + parallelization and robustness and simplify + configuration and development, it is + recommended for all new-style daemons that + communicate via listening sockets to employ + socket-based activation. In a socket-based + activation scheme the creation and binding of + the listening socket as primary communication + channel of daemons to local (and sometimes + remote) clients is moved out of the daemon + code and into the init system. Based on + per-daemon configuration the init system + installs the sockets and then hands them off + to the spawned process as soon as the + respective daemon is to be started. + Optionally activation of the service can be + delayed until the first inbound traffic + arrives at the socket, to implement on-demand + activation of daemons. However, the primary + advantage of this scheme is that all providers + and all consumers of the sockets can be + started in parallel as soon als all sockets + are established. In addition to that daemons + can be restarted with losing only a minimal + number of client transactions or even any + client request at all (the latter is + particularly true for state-less protocols, + such as DNS or syslog), because the socket + stays bound and accessible during the restart, + and all requests are queued while the daemon + cannot process them. + + New-style daemons which support socket + activation must be able to receive their + sockets from the init system, instead of of + creating and binding them themselves. For + details about the programming interfaces for + this scheme provided by systemd see + sd_listen_fds3 + and + sd-daemon7. For + details about porting existing daemons to + socket-based activation see below. With + minimal effort it is possible to implement + socket-based activation in addition to + traditional internal socket creation in the + same codebase in order to support both + new-style and old-style init systems from the + same daemon binary. + + systemd implements socket-based + activation via .socket + units, which are described in + systemd.socket5. When + configuring socket units for socket-based + activation it is essential that all listening + sockets are pulled in by the special target + unit sockets.target. It + is recommended to place a + WantedBy=sockets.target + directive in the [Install] + section, to automatically add such a + dependency on installation of a socket + unit. Unless + DefaultDependencies=no is + set the necessary ordering dependencies are + implicitly created for all socket units. For + more information about + sockets.target see + systemd.special7. It + is not necessary or recommended to place any + additional dependencies on socket units (for + example from + multi-user.target or + suchlike) when one is installed in + sockets.target. - Bus Activation + Bus-Based Activation + + When the D-Bus IPC system is used for + communication with clients, new-style daemons + should employ bus activation so that they are + automatically activated when a client + application accesses their IPC + interfaces. This is configured in D-Bus + service files (not to be confused with systemd + service unit files!). To ensure that D-Bus + uses systemd to start-up and maintain the + daemon use the + SystemdService= directive + in these service files, to configure the + matching systemd service for a D-Bus + service. e.g.: for a D-Bus service whose D-Bus + activation file is named + org.freedesktop.RealtimeKit.service, + make sure to set + SystemdService=rtkit-daemon.service + in that file, to bind it to the systemd + service + rtkit-daemon.service. This + is needed to make sure that the daemon is + started in a race-free fashion when activated + via multiple mechanisms simultaneously. - Socket Activation + Device-Based Activation + + Often, daemons that manage a particular + type of hardware should be activated only when + the hardware of the respective kind is plugged + in or otherwise becomes available. In a + new-style init system it is possible to bind + activation to hardware plug/unplug events. In + systemd, kernel devices appearing in the + sysfs/udev device tree can be exposed as units + if they are tagged with the string + "systemd". Like any other + kind of unit they may then pull in other units + when activated (i.e. Plugged in) and thus + implement device-based activation. Systemd + dependencies may be encoded in the udev + database via the + SYSTEMD_WANTS= + property. See + systemd.device5 + for details. Often it is nicer to pull in + services from devices only indirectly via + dedicated targets. Example: instead of pulling + in bluetoothd.service + from all the various bluetooth dongles and + other hardware available, pull in + bluetooth.target from them and + bluetoothd.service from + that target. This provides for nicer + abstraction and gives administrators the + option to enable + bluetoothd.service via + controlling a + bluetooth.target.wants/ + symlink uniformly with a command like + enable of + systemctl1 + instead of manipulating the udev + ruleset. - Writing Service Files + Path-Based Activation + + Often, runtime of daemons processing + spool files or directories (such as a printing + system) can be delayed until these file system + objects change state, or become + non-empty. New-style init systems provide a + way to bind service activation to file system + changes. systemd implements this scheme via + path-based activation configured in + .path units, as outlined + in + systemd.path5. - Installing Service Files + Timer-Based Activation + + Some daemons that implement clean-up + jobs that are intended to be executed in + regular intervals benefit from timer-based + activation. In systemd, this is implemented + via .timer units, as + described in + systemd.timer5. + + Other Forms of Activation + + Other forms of activation have been + suggested and implemented in some + systems. However, often there are simpler or + better alternatives, or they can be put + together of combinations of the schemes + above. Example: sometimes it appears useful to + start daemons or .socket + units when a specific IP address is configured + on a network interface, because network + sockets shall be bound to the + address. However, an alternative to implement + this is by utilizing the Linux IP_FREEBIND + socket option, as accessible via + FreeBind=yes in systemd + socket files (see + systemd.socket5 + for details). This option, when enabled, + allows sockets to be bound to a non-local, not + configured IP address, and hence allows + bindings to a particular IP address before it + actually becomes available, making such an + explicit dependency to the configured address + redundant. Another often suggested trigger for + service activation is low system + load. However, here too, a more convincing + approach might be to make proper use of + features of the operating system: in + particular, the CPU or IO scheduler of + Linux. Instead of scheduling jobs from + userspace based on monitoring the OS + scheduler, it is advisable to leave the + scheduling of processes to the OS scheduler + itself. systemd provides fine-grained access + to the CPU and IO schedulers. If a process + executed by the init system shall not + negatively impact the amount of CPU or IO + bandwith available to other processes, it + should be configured with + CPUSchedulingPolicy=idle + and/or + IOSchedulingClass=idle. Optionally, + this may be combined with timer-based + activation to schedule background jobs during + runtime and with minimal impact on the system, + and remove it from the boot phase + itself. + + + + + Integration with Systemd + + + Writing Systemd Unit Files + + When writing systemd unit files, it is + recommended to consider the following + suggestions: + + + If possible do not use + the Type=forking + setting in service files. But if you + do, make sure to set the PID file path + using PIDFile=. See + systemd.service5 + for details. + + If your daemon + registers a D-Bus name on the bus, + make sure to use + Type=dbus in the + service file if + possible. + + Make sure to set a + good human-readable description string + with + Description=. + + Do not disable + DefaultDependencies=, + unless you really know what you do and + your unit is involved in early boot or + late system shutdown. + + Normally, little if + any dependencies should need to + be defined explicitly. However, if you + do configure explicit dependencies, only refer to + unit names listed on + systemd.special7 + or names introduced by your own + package to keep the unit file + operating + system-independent. + + Since not all syslog + implementations are socket-activatable + yet, it is recommended to place an + After=syslog.target + dependency in service files for + daemons that can log to + syslog. syslog.target + then either pulls in the syslog daemon + itself or simply the activation + socket. A Wants= or + even Requires= + dependency should generally not be + added, since it should be up to the + administrator whether he wants to + enable logging or not, and most syslog + clients work fine if no log daemon is + running. + + Make sure to include + an [Install] + section including installation + information for the unit file. See + systemd.unit5 + for details. To activate your service + on boot make sure to add a + WantedBy=multi-user.target + or + WantedBy=graphical.target + directive. To activate your socket on + boot, make sure to add + WantedBy=sockets.target. Usually + you also want to make sure that when + your service is installed your socket + is installed too, hence add + Also=foo.socket in + your service file + foo.service, for + a hypothetical program + foo. + + + + + + Installing Systemd Service Files + + At the build installation time + (e.g. make install during + package build) packages are recommended to + install their systemd unit files in the + directory returned by pkg-config + systemd + --variable=systemdsystemunitdir (for + system services), resp. pkg-config + systemd + --variable=systemdsessionunitdir + (for session services). This will make the + services available in the system on explicit + request but not activate them automatically + during boot. Optionally, during package + installation (e.g. rpm -i + by the administrator) symlinks should be + created in the systemd configuration + directories via the enable + command of the + systemctl1 + tool, to activate them automatically on + boot. + + Packages using + autoconf1 + are recommended to use a configure script + excerpt like the following to determine the + unit installation path during source + configuration: + + PKG_PROG_PKG_CONFIG +AC_ARG_WITH([systemdsystemunitdir], + AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]), + [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)]) +AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir]) +AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir"]) + + This snippet allows automatic + installation of the unit files on systemd + machines, and optionally allows their + installation even on machines lacking + systemd. (Modification of this snippet for the + session unit directory is left as excercise to the + reader.) + + Additionally, to ensure that + make distcheck continues to + work, it is recommended to add the following + to the top-level Makefile.am + file in + automake1-based + projects: + + DISTCHECK_CONFIGURE_FLAGS = \ + --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir) + + Finally, unit files should be installed in the system with an automake excerpt like the following: + + if HAVE_SYSTEMD +systemdsystemunit_DATA = \ + foobar.socket \ + foobar.service +endif + + In the + rpm8 + .spec file use a snippet like + the following to enable/disable the service + during installation/deinstallation. Consult + the packaging guidelines of your distribution + for details and the equivalent for other + package managers: + + %post +if [ $1 -eq 1 ]; then + # Enable (but don't start) the units by default + /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&1 || : + + # Alternatively, just call /bin/systemctl daemon-reload here, + # if the daemon should not be enabled by default on package + # installation +fi + +%preun +if [ $1 -eq 0 ]; then + # Disable and stop the units + /bin/systemctl disable foobar.service foobar.socket >/dev/null 2>&1 || : + /bin/systemctl stop foobar.service foobar.socket >/dev/null 2>&1 || : +fi + +%postun +if [ $1 -ge 1 ] ; then + # On upgrade, reload init system configuration if we changed unit files + /bin/systemctl daemon-reload >/dev/null 2>&1 || : + # On upgrade, restart the daemon + /bin/systemctl try-restart foobar.service >/dev/null 2>&1 || : +fi + + Depending on whether your service should + or should not be started/stopped/restarted + during package installation, deinstallation or + upgrade, a different set of commands may be + specified. See + systemctl1 + for details. + + To facilitate upgrades from a package + version that shipped only SysV init scripts to + a package version that ships both a SysV init + script and a native systemd service file, use + a fragment like the following: + + %triggerin -- foobar < 0.47.11-1 +if /sbin/chkconfig foobar ; then + /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&1 || : +fi + + Where 0.47.11-1 is the first package + version that includes the native unit + file. This fragment will ensure that the first + time the unit file is installed it will be + enabled if and only if the SysV init script is + enabled, thus making sure that the the enable + status is not changed. Note that + chkconfig is a command + specific Fedora which can be used to check + whether a SysV init script is enabled. Other + operating systems will have to use different + commands here. + + + Porting Existing Daemons + + Since new-style init systems such as systemd are + compatible with traditional SysV init systems it is + not strictly necessary to port existing daemons to the + new style. However doing so offers additional + functionality to the daemons as well as simplifying + integration into new-style init systems. + + To port an existing SysV compatible daemon the + following steps are recommended: + + + If not already implemented, + add an optional command line switch to the + daemon to disable daemonization. This is + useful not only for using the daemon in + new-style init systems, but also to ease + debugging. + + If the daemon offers + interfaces to other software running on the + local system via local AF_UNIX sockets, + consider implementing socket-based activation + (see above). Usually a minimal patch is + sufficient to implement this: Extend the + socket creation in the daemon code so that + sd_listen_fds3 + is checked for already passed sockets + first. If sockets are passed (i.e. when + sd_listen_fds() returns a + positive value), skip the socket creation step + and use the passed sockets. Secondly, ensure + that the file-system socket nodes for local + AF_UNIX sockets used in the socket-based + activation are not removed when the daemon + shuts down, if sockets have been + passed. Third, if the daemon normally closes + all remaining open file descriptors as part of + its initialization, the sockets passed from + the init system must be spared. Since + new-style init systems guarantee that no + left-over file descriptors are passed to + executed processes, it might be a good choice + to simply skip the closing of all remaining + open file descriptors if sockets are + passed. + + Write and install a systemd + unit file for the service (and the sockets if + socket-based activation is used, as well as a + path unit file, if the daemon processes a + spool directory), see above for + details. + + If the daemon exposes + interfaces via D-Bus, write and install a + D-Bus activation file for the service, see + above for details. + + - See Also - - daemon3, - sd_listen_fds3 - + See Also + + systemd1, + sd-daemon7, + sd_listen_fds3, + sd_notify3, + daemon3, + systemd.service5 +