diff --git a/man/daemon.xml b/man/daemon.xml
index 853b3bb8147..01ab0f3b511 100644
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -57,7 +57,10 @@
in SysV Unix. Modern daemons should follow a simpler
yet more powerful scheme (here called "new-style"
daemons), as implemented by
- systemd1.
+ 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
@@ -252,26 +255,35 @@
recommendations for SysV init
scripts.
- As much as possible,
- rely on systemd's functionality to
- limit the access 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. See
- systemd.exec5
- for the available
- controls.
-
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.
+ 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
@@ -345,18 +357,308 @@
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
+ 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-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.
+
+
+
+ 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 tool like
+ systemd-install1
+ instead of manipulating the udev
+ ruleset.
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.
+
+ 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
@@ -416,7 +718,7 @@
- Installing Service Files
+ Installing Systemd Service Files
At the build installation time
(e.g. make install during
@@ -488,7 +790,7 @@ endif
during installation/deinstallation. Consult
the packaging guidelines of your distribution
for details and the equivalent for other
- packaging managers:
+ package managers:
%post
/usr/bin/systemd-install enable foobar.service foobar.socket >/dev/null 2>&1 || :
@@ -499,85 +801,70 @@ if [ "$1" -eq 0 ]; then
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.
-
-
-
-
+
+ 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 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 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.
+
+
See Also
@@ -587,7 +874,8 @@ fi
sd-daemon7,
sd_listen_fds3,
sd_notify3,
- daemon3
+ daemon3,
+ systemd.service5
diff --git a/man/systemd.device.xml b/man/systemd.device.xml
index a5395a1d489..c5306430fb6 100644
--- a/man/systemd.device.xml
+++ b/man/systemd.device.xml
@@ -64,9 +64,11 @@
systemd.unit5
for the common options of all unit configuration
files. The common configuration items are configured
- in the generic [Unit] and [Install] sections. A
- separate [Device] section does not exist, since no
- device-specific options may be configured.
+ in the generic [Unit] and
+ [Install] sections. A separate
+ [Device] section does not exist,
+ since no device-specific options may be
+ configured.
systemd will automatically create dynamic device
units for all kernel devices that are marked with the
@@ -100,9 +102,15 @@
Adds dependencies of
type Wants from
this unit to all listed units. This
- may be used to activate arbitrary units,
- when a specific device becomes
- available.
+ may be used to activate arbitrary
+ units, when a specific device becomes
+ available. Note that this and the
+ other tags are not taken into account
+ unless the device is tagged with the
+ "systemd" string in
+ the udev database, because otherwise
+ the device is not exposed as systemd
+ unit.
diff --git a/man/systemd.xml b/man/systemd.xml
index 27756723b15..007705e4943 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -196,6 +196,112 @@
+
+ Concepts
+
+ systemd provides a dependency system between
+ various entities called "units". Units encapsulate
+ various objects that are relevant for system boot-up
+ and maintainance. The majority of units are configured
+ in unit configuration files, whose syntax and basic
+ set of options is described in
+ systemd.unit5,
+ however some are created automatically from other
+ configuration or dynamically from system state. Units
+ may be active (meaning started, bound, plugged in, ...
+ depending on the unit type), or inactive (meaning
+ stopped, unbound, unplugged, ...), as well is in the
+ process of being activated or deactivated,
+ i.e. between the two states. The following unit types
+ are available:
+
+
+ Service units, which control
+ daemons and the processes they consist of. For
+ details see
+ systemd.service5.
+
+ Socket units, which
+ encapsulate local IPC or network sockets in
+ the system, useful for socket-based
+ activation. For details about socket units see
+ systemd.socket5,
+ for details on socket-based activation and
+ other forms of activation, see
+ daemon7.
+
+ Target units are useful to
+ group units, or provide well-known
+ synchronization points during boot-up, see
+ systemd.target5.
+
+ Device units expose kernel
+ devices in systemd and may be used to
+ implement device-based activation. For details
+ see
+ systemd.device5.
+
+ Mount units control mount
+ points in the file system, for details see
+ systemd.mount5.
+
+ Automount units provide
+ automount capabilities, for on-demand mounting
+ of file systems as well as parallelized
+ boot-up. See
+ systemd.automount5.
+
+ Snapshot units can be used to
+ temporarily save the state of the set of
+ systemd units, which later may be restored by
+ activating the saved snapshot unit. For more
+ information see
+ systemd.automount5.
+
+ Timer units are useful for
+ triggering activation of other units based on
+ timers. You may find details in
+ systemd.timer5.
+
+ Swap units are very similar to
+ mount units and encapsulated memory swap
+ partitions or files of the operating
+ systemd. They are described in systemd.swap5.
+
+ Path units may be used
+ activate other services when file system
+ objects change or are modified. See
+ systemd.path5.
+
+
+
+ Units are named as their configuration
+ files. Some units have special semantics. A detailed
+ list you may find in
+ systemd.special7.
+
+ On boot systemd activates the target unit
+ default.target whose job it is to
+ activate on-boot services and other on-boot units by
+ pulling them in via dependencies. Usually the unit
+ name is just an alias (symlink) for either
+ graphical.target (for
+ fully-featured boots into the UI) or
+ multi-user.target (for limited
+ console-only boots for use in embedded or server
+ environments, or similar; a subset of
+ graphical.target). However it is at the discretion of
+ the administrator to configure it as an alias to any
+ other target unit. See
+ systemd.special7
+ for details about these target units.
+
+ For more information about the concepts and
+ ideas behind systemd please refer to the Original
+ Announcement Document.
+
+
Directories