From 62adf224d1d3e225de072a2815dd50e973230f5c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sat, 3 Jul 2010 19:54:00 +0200 Subject: [PATCH] man: various man page updates --- man/daemon.xml | 369 ++++++++++++++++++++++++++++++++----- man/systemd.path.xml | 11 ++ man/systemd.service.xml | 69 ++++--- man/systemd.socket.xml | 15 ++ man/systemd.special.xml.in | 81 +++++--- man/systemd.target.xml | 14 +- man/systemd.timer.xml | 11 ++ man/systemd.unit.xml | 36 +++- 8 files changed, 505 insertions(+), 101 deletions(-) diff --git a/man/daemon.xml b/man/daemon.xml index 1cddf38f..853b3bb8 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + daemon @@ -55,8 +55,9 @@ 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. SysV Daemons @@ -64,7 +65,7 @@ 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, + steps are unnecessary for new-style daemons (see below), and should only be implemented if compatibility with SysV is essential. @@ -80,7 +81,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 +92,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 +130,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 +142,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 +169,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 +219,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,9 +247,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). + scheme as defined in the LSB + recommendations for SysV init + scripts. As much as possible, rely on systemd's functionality to @@ -220,7 +261,10 @@ implementing your own, rely on systemd's privilege dropping code instead of implementing it in the - daemon, and similar. + daemon, and similar. See + systemd.exec5 + for the available + controls. If possible and applicable expose the daemon's control @@ -239,8 +283,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 @@ -255,20 +299,21 @@ 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,30 +321,259 @@ (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. - Bus Activation + Socket-Based Activation - Socket Activation + Bus-Based Activation - Writing Service Files + Path-Based Activation + + + + 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 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. + + 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. + + Installing 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=systemdsystemnunitdir + (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 + systemd-install1 + 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 + packaging managers: + + %post +/usr/bin/systemd-install enable foobar.service foobar.socket >/dev/null 2>&1 || : + +%preun +if [ "$1" -eq 0 ]; then + /usr/bin/systemd-install disable foobar.service foobar.socket >/dev/null 2>&1 || : +fi + + + + + 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 this offers additional + functionality to the daemons as well as it + simplifies 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 createn 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 + file descriptors 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. + + @@ -309,8 +583,11 @@ See Also systemd1, - daemon3, - sd_listen_fds3 + systemd-install1, + sd-daemon7, + sd_listen_fds3, + sd_notify3, + daemon3 diff --git a/man/systemd.path.xml b/man/systemd.path.xml index 77219009..d910d2c5 100644 --- a/man/systemd.path.xml +++ b/man/systemd.path.xml @@ -87,6 +87,17 @@ If an path unit is beneath another mount point in the file system hierarchy, a dependency between both units is created automatically. + + Unless DefaultDependencies= + is set to , path units will + implicitly have dependencies of type + Conflicts= and + Before= on + shutdown.target. These ensure + that path units are terminated cleanly prior to system + shutdown. Only path units involved with early boot or + late system shutdown should disable this + option. diff --git a/man/systemd.service.xml b/man/systemd.service.xml index b01641f1..91d6d094 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -64,27 +64,44 @@ systemd.unit5 for the common options of all unit configuration files. The common configuration items are configured - in the generic [Unit] and [Install] sections. The - service specific configuration options are configured - in the [Service] section. + in the generic [Unit] and + [Install] sections. The service + specific configuration options are configured in the + [Service] section. Additional options are listed in systemd.exec5, which define the execution environment the commands are executed in. + + Unless DefaultDependencies= + is set to , service units will + implicitly have dependencies of type + Requires= and + After= on + basic.target as well as + dependencies of type Conflicts= and + Before= on + shutdown.target. These ensure + that normal service units pull in basic system + initialization, and are terminated cleanly prior to + system shutdown. Only services involved with early + boot or late system shutdown should disable this + option. Options - Service files must include a [Service] section, - which carries information about the service and the - process it supervises. A number of options that may be - used in this section are shared with other unit - types. These options are documented in + Service files must include a + [Service] section, which carries + information about the service and the process it + supervises. A number of options that may be used in + this section are shared with other unit types. These + options are documented in systemd.exec5. The - options specific to the [Service] section of service - units are the following: + options specific to the [Service] + section of service units are the following: @@ -143,14 +160,18 @@ Behaviour of is similar to - , however it - is expected that the daemon acquires a + , however it is + expected that the daemon acquires a name on the D-Bus bus, as configured by BusName=. systemd will proceed starting follow-up units after the D-Bus bus name has been - acquired. + acquired. Service units with this + option configured implicitly have + dependencies on the + dbus.target + unit. Behaviour of is similar to @@ -163,10 +184,13 @@ starting follow-up units after this notification message has been sent. If this option is used - (see + NotifyAccess= (see below) must be set to open access to the notification socket provided by - systemd. + systemd. If + NotifyAccess= is not + set, it will be implicitly set to + . @@ -220,11 +244,12 @@ services. This option may not be specified more than once. Optionally, if the absolute file name is prefixed - with @, the second token will be - passed as argv[0] to the executed - process, followed by the further - arguments specified. Unless - is set, + with @, the second + token will be passed as + argv[0] to the + executed process, followed by the + further arguments specified. Unless + Type=forking is set, the process started via this command line will be considered the main process of the @@ -312,7 +337,7 @@ forcibly via SIGTERM, and after another delay of this time with SIGKILL. (See - + KillMode= below.) Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout @@ -450,7 +475,7 @@ Processes will first be terminated via SIGTERM. If then after a delay (configured via the - option) + TimeoutSec= option) processes still remain, the termination request is repeated with the SIGKILL signal. See diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 986ef8c0..6154b304 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -95,6 +95,21 @@ which services are instantiated for each incoming connection. + Unless DefaultDependencies= + is set to , socket units will + implicitly have dependencies of type + Requires= and + After= on + sysinit.target as well as + dependencies of type Conflicts= and + Before= on + shutdown.target. These ensure + that socket units pull in basic system + initialization, and are terminated cleanly prior to + system shutdown. Only sockets involved with early + boot or late system shutdown should disable this + option. + Socket units may be used to implement on-demand starting of services, as well as parallelized starting of services. diff --git a/man/systemd.special.xml.in b/man/systemd.special.xml.in index 79c6db1a..49dc3892 100644 --- a/man/systemd.special.xml.in +++ b/man/systemd.special.xml.in @@ -51,6 +51,7 @@ basic.target, ctrl-alt-del.target, @SPECIAL_DBUS_SERVICE@, + dbus.target, default.target, display-manager.service, emergency.service, @@ -78,8 +79,8 @@ sockets.target, swap.target, sysinit.target, - syslog.target, @SPECIAL_SYSLOG_SERVICE@, + syslog.target, systemd-initctl.service, systemd-initctl.socket, systemd-logger.service, @@ -141,6 +142,28 @@ up systemd will connect to it and register its service. + + Units should generally + avoid depending on this unit + directly and instead refer to + the + dbus.target + unit instead, which pulls this + one in directly or indirectly + via socket-based activation. + + + + dbus.target + + Administrators should + ensure that this target pulls + in a service unit with the + name or alias of + @SPECIAL_DBUS_SERVICE@ + (or a socket unit that + activates this + service). @@ -522,28 +545,6 @@ files. - - syslog.target - - systemd automatically - adds dependencies of type - After for this target unit to - all SysV init script service - units with an LSB header - referring to the - $syslog - facility. - - Administrators should - ensure that this target pulls - in a service unit with the - name or alias of - @SPECIAL_SYSLOG_SERVICE@ - (or a socket unit that - activates this - service). - - sysinit.target @@ -571,11 +572,37 @@ and use it for logging if it has been configured for that. - Applications should - generally not depend on this - service, and depend on + + Units should generally + avoid depending on this unit + directly and instead refer to + the syslog.target - instead. + unit instead, which pulls this + one in directly or indirectly + via socket-based activation. + + + + syslog.target + + systemd automatically + adds dependencies of type + After for this target unit to + all SysV init script service + units with an LSB header + referring to the + $syslog + facility. + + Administrators should + ensure that this target pulls + in a service unit with the + name or alias of + @SPECIAL_SYSLOG_SERVICE@ + (or a socket unit that + activates this + service). diff --git a/man/systemd.target.xml b/man/systemd.target.xml index 88a9e6ea..6f3bc182 100644 --- a/man/systemd.target.xml +++ b/man/systemd.target.xml @@ -76,12 +76,22 @@ dependencies between units. Among other things, target units are a more flexible replacement for SysV runlevels in the classic SysV init system. (And for - compatibility reasons there exist special + compatibility reasons special target units such as - runlevel3.target which are used by + runlevel3.target exist which are used by the SysV runlevel compatibility code in systemd. See systemd.special7 for details). + + Unless + DefaultDependencies= is set to + , target units will + implicitly complement all configured dependencies of type + Wants=, + Requires=, + RequiresOverridable= with + dependencies of type After=. + diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index 7a4cd348..ef89693f 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -76,6 +76,17 @@ matching service foo.service. The unit to activate may be controlled by Unit= (see below). + + Unless DefaultDependencies= + is set to , timer units will + implicitly have dependencies of type + Conflicts= and + Before= on + shutdown.target. These ensure + that timer units are stopped cleanly prior to system + shutdown. Only timer units involved with early boot or + late system shutdown should disable this + option. diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 9c4269f3..26272c44 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -215,10 +215,10 @@ Description= A free-form string - describing the unit. This is intended for use - in UIs wanting to show - descriptive information along with the - unit name. + describing the unit. This is intended + for use in UIs to show descriptive + information along with the unit + name. @@ -451,6 +451,34 @@ . + + DefaultDependencies= + + Takes a boolean + argument. If + (the default), a few default + dependencies will implicitly be + created for the unit. The actual + dependencies created depend on the + unit type. For example, for service + units, these dependencies ensure that + the service is started only after + basic system initialization is + complete and is properly terminated on + system shutdown. See the respective + man pages for details. Generally, only + services involved with early boot or + late shutdown should set this option + to . It is + highly recommended to leave this + option enabled for the majority of + common units. If set to + this option + does not disable all implicit + dependencies, just non-essential + ones. + + Unit file may include a [Install] section, which -- 2.39.5