X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fdaemon.xml;h=7790420c6eb7154cfa80625f24fdb9db43cb0e2b;hp=f592e7d6e26531538b57ae6b8562affae5c6be91;hb=e7176abbe818c75c6acd90227a7a84c3e05fee31;hpb=af2d49f70bcff20efaf2d69aecaf4b3e898ff1fa diff --git a/man/daemon.xml b/man/daemon.xml index f592e7d6e..7790420c6 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -8,16 +8,16 @@ 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 + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 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. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> @@ -44,7 +44,7 @@ daemon - Writing and Packaging System Daemons + Writing and packaging system daemons @@ -79,7 +79,7 @@ descriptors 0, 1, 2). This ensures that no accidentally passed file descriptor stays around in the daemon - process. On Linux this is best + process. On Linux, this is best implemented by iterating through /proc/self/fd, with a fallback of iterating from file @@ -92,7 +92,7 @@ best done by iterating through the available signals up to the limit of _NSIG and resetting them to - SIG_DFL. + SIG_DFL. Reset the signal mask using @@ -115,14 +115,14 @@ In the child, call fork() again, to - ensure the daemon can never re-aquire + ensure that the daemon can never re-acquire 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 + daemon process is re-parented to init/PID 1, as all daemons should be. @@ -150,15 +150,15 @@ getpid()) to a PID file, for example /var/run/foobar.pid - (for a hypothetical daemon "foobar"), + (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 + it is verified at the same time that the PID previously stored in the PID file no longer exists or belongs to a - foreign process. Commonly some kind of + foreign process. Commonly, some kind of file locking is employed to implement this logic. @@ -167,7 +167,7 @@ applicable. From the daemon - process notify the original process + process, notify the original process started that initialization is complete. This can be implemented via an unnamed pipe or similar @@ -181,11 +181,11 @@ exit() in the original process. The process that invoked the daemon must be able to - rely that this + rely on that this exit() happens after initialization is complete and all external communication channels - established and + are established and accessible. @@ -196,8 +196,8 @@ 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 + behavior optional and configurable via a + command line argument to ease debugging as well as to simplify integration into systems using systemd. @@ -211,20 +211,20 @@ runtime and simplifies their implementation. - For developing a new-style daemon none + 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 + the init system, it is recommended not to 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 + a clean process context: 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 @@ -237,11 +237,11 @@ to implement the following: - If SIGTERM is + If SIGTERM is received, shut down the daemon and exit cleanly. - If SIGHUP is received, + If SIGHUP is received, reload the configuration files, if this applies. @@ -256,7 +256,7 @@ scripts. If possible and - applicable expose the daemon's control + applicable, expose the daemon's control interface via the D-Bus IPC system and grab a bus name as last step of initialization. @@ -271,10 +271,10 @@ for details. As much as possible, - rely on the init systemd's + rely on the init system's functionality to limit the access of the daemon to files, services and - other resources. i.e. in the case of + 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 @@ -285,7 +285,7 @@ controls. If D-Bus is used, make - your daemon bus-activatable, via + your daemon bus-activatable by supplying a D-Bus service activation configuration file. This has multiple advantages: your daemon may be started @@ -293,7 +293,7 @@ parallel to other daemons requiring it -- which maximizes parallelization and boot-up speed; your daemon can be - restarted on failure, without losing + restarted on failure without losing any bus requests, as the bus queues requests for activatable services. See below for details. @@ -304,17 +304,17 @@ socket, it should be made socket-activatable following the scheme pointed out below. Like D-Bus - activation this enables on-demand + 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 + protocols (such as syslog, DNS), a daemon implementing socket-based activation can be restarted without losing a single request. See below for details. - If applicable a daemon + If applicable, a daemon should notify the init system about startup completion or status updates via the @@ -323,11 +323,11 @@ Instead of using the syslog() call to log directly to the - system logger, a new-style daemon may + system syslog service, 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 + priorities are necessary, these can be encoded by prefixing individual log lines with strings like "<4>" (for log priority 4 "WARNING" in the @@ -343,9 +343,9 @@ kind of logging may be enabled by setting StandardError=syslog - in the service unit file. For details + in the service unit file. For details, see - sd-daemon7 + sd-daemon3 and systemd.exec5. @@ -374,9 +374,9 @@ 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 + unconditionally, it is a good idea to implement some of the various activation schemes outlined below, in - order to maximize parallelization: if a daemon + 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 @@ -384,7 +384,7 @@ 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 + case of sockets) until the activation is completed. @@ -397,9 +397,9 @@ url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB Linux Standard Base Core Specification. This method of - activation is supported ubiquitiously on Linux + activation is supported ubiquitously on Linux init systems, both old-style and new-style - systems. Among other issues SysV init scripts + 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 @@ -409,7 +409,7 @@ In systemd, if the developer or administrator wants to make sure a service or - other unit is activated automatically on boot + other unit is activated automatically on boot, it is recommended to place a symlink to the unit file in the .wants/ directory of either @@ -434,25 +434,25 @@ 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 + 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 + 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 + Optionally, activation of the service can be delayed until the first inbound traffic - arrives at the socket, to implement on-demand + 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 as all sockets - are established. In addition to that daemons + are established. In addition to that, daemons can be restarted with losing only a minimal - number of client transactions or even any + 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 @@ -462,16 +462,16 @@ New-style daemons which support socket activation must be able to receive their - sockets from the init system, instead of of + sockets from the init system instead of creating and binding them themselves. For details about the programming interfaces for - this scheme provided by systemd see + this scheme provided by systemd, see sd_listen_fds3 and - sd-daemon7. For + sd-daemon3. For details about porting existing daemons to - socket-based activation see below. With - minimal effort it is possible to implement + 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 @@ -483,20 +483,20 @@ units, which are described in systemd.socket5. When configuring socket units for socket-based - activation it is essential that all listening + 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 + section to automatically add such a dependency on installation of a socket unit. Unless DefaultDependencies=no is - set the necessary ordering dependencies are + set, the necessary ordering dependencies are implicitly created for all socket units. For more information about - sockets.target see + sockets.target, see systemd.special7. It is not necessary or recommended to place any additional dependencies on socket units (for @@ -518,16 +518,16 @@ 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 + daemon, use the SystemdService= directive - in these service files, to configure the + 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 + 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 + in that file to bind it to the systemd service rtkit-daemon.service. This is needed to make sure that the daemon is @@ -542,23 +542,23 @@ 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 + 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 + 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 + for details. Often, it is nicer to pull in services from devices only indirectly via - dedicated targets. Example: instead of pulling + dedicated targets. Example: Instead of pulling in bluetoothd.service from all the various bluetooth dongles and other hardware available, pull in @@ -610,10 +610,10 @@ Other forms of activation have been suggested and implemented in some - systems. However, often there are simpler or + systems. However, there are often simpler or better alternatives, or they can be put together of combinations of the schemes - above. Example: sometimes it appears useful to + 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 @@ -634,7 +634,7 @@ 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 + 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 @@ -644,7 +644,7 @@ 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 + bandwidth available to other processes, it should be configured with CPUSchedulingPolicy=idle and/or @@ -668,7 +668,7 @@ suggestions: - If possible do not use + If possible, do not use the Type=forking setting in service files. But if you do, make sure to set the PID file path @@ -705,39 +705,21 @@ 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 + 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 + WantedBy=sockets.target. Usually, you also want to make sure that when - your service is installed your socket + your service is installed, your socket is installed too, hence add Also=foo.socket in your service file @@ -753,12 +735,12 @@ At the build installation time (e.g. make install during - package build) packages are recommended to + 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 + system services) or pkg-config systemd --variable=systemduserunitdir (for user services). This will make the @@ -766,12 +748,12 @@ request but not activate them automatically during boot. Optionally, during package installation (e.g. rpm -i - by the administrator) symlinks should be + 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 + tool to activate them automatically on boot. Packages using @@ -795,7 +777,7 @@ AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_sy machines, and optionally allows their installation even on machines lacking systemd. (Modification of this snippet for the - user unit directory is left as excercise to the + user unit directory is left as an exercise for the reader.) Additionally, to ensure that @@ -819,48 +801,49 @@ endif In the rpm8 - .spec file use a snippet like - the following to enable/disable the service - during installation/deinstallation. Consult + .spec file, use snippets + like the following to enable/disable the + service during + installation/deinstallation. This makes use of + the RPM macros shipped along systemd. Consult the packaging guidelines of your distribution for details and the equivalent for other - package managers: + package managers. + + At the top of the file: + + BuildRequires: systemd +%{?systemd_requires} + + And as scriptlets, further down: %post -if [ $1 -eq 1 ]; then - # On install (not upgrade), 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 >/dev/null 2>&1 || : - # here, if the daemon should not be enabled by default on - # installation -fi +%systemd_post foobar.service foobar.socket %preun -if [ $1 -eq 0 ]; then - # On uninstall (not upgrade), 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 +%systemd_preun foobar.service foobar.socket %postun -# Reload init system configuration, to make systemd honour changed -# or deleted unit files -/bin/systemctl daemon-reload >/dev/null 2>&1 || : -if [ $1 -ge 1 ] ; then - # On upgrade (not uninstall), optionally, 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. +%systemd_postun + + If the service shall be restarted during + upgrades, replace the + %postun scriptlet above + with the following: + + %postun +%systemd_postun_with_restart foobar.service + + Note that + %systemd_post and + %systemd_preun expect the + names of all units that are installed/removed + as arguments, separated by + spaces. %systemd_postun + expects no + arguments. %systemd_postun_with_restart + expects the units to restart as + arguments. To facilitate upgrades from a package version that shipped only SysV init scripts to @@ -869,14 +852,14 @@ fi a fragment like the following: %triggerun -- foobar < 0.47.11-1 -if /sbin/chkconfig foobar ; then - /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&1 || : +if /sbin/chkconfig --level 5 foobar ; then + /bin/systemctl --no-reload 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 + 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 enable status is not changed. Note that @@ -892,13 +875,13 @@ fi Porting Existing Daemons Since new-style init systems such as systemd are - compatible with traditional SysV init systems it is + compatible with traditional SysV init systems, it is not strictly necessary to port existing daemons to the - new style. However doing so offers additional + 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 + To port an existing SysV compatible daemon, the following steps are recommended: @@ -911,9 +894,9 @@ fi If the daemon offers interfaces to other software running on the - local system via local AF_UNIX sockets, + local system via local AF_UNIX sockets, consider implementing socket-based activation - (see above). Usually a minimal patch is + (see above). Usually, a minimal patch is sufficient to implement this: Extend the socket creation in the daemon code so that sd_listen_fds3 @@ -922,8 +905,8 @@ fi 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 + 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 @@ -955,7 +938,7 @@ fi See Also systemd1, - sd-daemon7, + sd-daemon3, sd_listen_fds3, sd_notify3, daemon3,