X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.xml;h=5129fbb050139865baf74d31a64e0d6f2fd5adac;hp=f754348ce1a06033ba4e4c8ce43005ac1f358c40;hb=253ee27a0c7a410d27d490bb79ea97caed6a2b68;hpb=160cd5c9aa2301892e13950015de7968c764340d
diff --git a/man/systemd.xml b/man/systemd.xml
index f754348ce..5129fbb05 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -44,7 +44,8 @@
systemd
- systemd System and Session Manager
+ init
+ systemd System and Service Manager
@@ -59,19 +60,26 @@
Description
- systemd is a system and session manager for
+ systemd is a system and service manager for
Linux operating systems. When run as first process on
- boot (as PID 1) it may act as init system that brings
- up and maintains userspace.
+ boot (as PID 1), it acts as init system that brings
+ up and maintains userspace services.
- For compatibility with SysV if systemd is called
+ For compatibility with SysV, if systemd is called
as init and a PID that is not
- 1 it will execute telinit and pass
+ 1, it will execute telinit and pass
all command line arguments unmodified. That means
init and telinit
are mostly equivalent when invoked from normal login sessions. See
telinit8
for more information.
+
+ When run as system instance, systemd interprets
+ the configuration file
+ system.conf, otherwise
+ user.conf. See
+ systemd.conf5
+ for more information.
@@ -87,28 +95,6 @@
Prints a short help
text and exits.
-
-
-
- Set default unit to
- activate on startup. If not specified
- defaults to
- default.target.
-
-
-
-
- Tell systemd to run in
- a particular mode. Argument is one of
- ,
- . Normally it
- should not be necessary to pass this
- option, as systemd automatically
- detects the mode it is started
- in. This call is hence of little use
- except for
- debugging.
-
@@ -122,29 +108,112 @@
Dump understood unit
configuration items. This outputs a
- terse list of configuration items
- understood in unit definition
- files.
-
-
-
-
- Ask for confirmation when spawning processes.
+ terse but complete list of
+ configuration items understood in unit
+ definition files.
Extract D-Bus
interface introspection data. This is
- mostly useful at build ot install time
+ mostly useful at install time
to generate data suitable for the
D-Bus interfaces
repository. Optionally the interface
name for the introspection data may be
- specified. If omitted the
+ specified. If omitted, the
introspection data for all interfaces
is dumped.
+
+
+
+ Set default unit to
+ activate on startup. If not specified
+ defaults to
+ default.target.
+
+
+
+
+
+ Tell systemd to run a
+ system instance (resp. user
+ instance), even if the process ID is
+ not 1 (resp. is 1), i.e. systemd is
+ not (resp. is) run as init process.
+ Normally it should not be necessary to
+ pass these options, as systemd
+ automatically detects the mode it is
+ started in. These options are hence of
+ little use except for debugging. Note
+ that it is not supported booting and
+ maintaining a full system with systemd
+ running in
+ mode, but PID not 1. In practice,
+ passing explicitly is
+ only useful in conjunction with
+ .
+
+
+
+
+ Dump core on
+ crash. This switch has no effect when
+ run as user
+ instance.
+
+
+
+
+ Run shell on
+ crash. This switch has no effect when
+ run as user
+ instance.
+
+
+
+
+ Ask for confirmation
+ when spawning processes. This switch
+ has no effect when run as user
+ instance.
+
+
+
+
+ Show terse service
+ status information while booting. This
+ switch has no effect when run as user
+ instance. Takes a boolean argument
+ which may be omitted which is
+ interpreted as
+ .
+
+
+
+
+ Controls whether
+ output of SysV init scripts will be
+ directed to the console. This switch
+ has no effect when run as user
+ instance. Takes a boolean argument
+ which may be omitted which is
+ interpreted as
+ .
+
+
+
+
+ Set log
+ target. Argument must be one of
+ ,
+ ,
+ ,
+ ,
+ .
+
@@ -161,17 +230,6 @@
,
.
-
-
-
- Set log
- target. Argument must be one of
- ,
- ,
- ,
- ,
- .
-
@@ -192,52 +250,831 @@
it defaults to
.
+
+
+
-
+ Sets the default
+ output resp. error output for all
+ services and sockets, i.e. controls
+ the default for
+
+ resp.
+ (see
+ systemd.exec5
+ for details). Takes one of
+ ,
+ ,
+ ,
+ ,
+ ,
+ ,
+ . If the
+ argument is omitted it defaults to
+ .
+
+
+ Concepts
+
+ systemd provides a dependency system between
+ various entities called "units". Units encapsulate
+ various objects that are relevant for system boot-up
+ and maintenance. 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, see below), or
+ 'inactive' (meaning stopped, unbound, unplugged, ...),
+ as well as in the process of being activated or
+ deactivated, i.e. between the two states (these states
+ are called 'activating', 'deactivating'). A special
+ 'failed' state is available as well which is very
+ similar to 'inactive' and is entered when the service
+ failed in some way (process returned error code on
+ exit, or crashed, or an operation timed out). If this
+ state is entered the cause will be logged, for later
+ reference. Note that the various unit types may have a
+ number of additional substates, which are mapped to
+ the five generalized unit states described
+ here.
+
+ 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.snapshot5.
+
+ 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 encapsulate memory swap
+ partitions or files of the operating
+ system. They are described in systemd.swap5.
+
+ Path units may be used
+ to 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 is available in
+ systemd.special7.
+
+ systemd knows various kinds of dependencies,
+ including positive and negative requirement
+ dependencies (i.e. Requires= and
+ Conflicts=) as well as ordering
+ dependencies (After= and
+ Before=). NB: ordering and
+ requirement dependencies are orthogonal. If only a
+ requirement dependency exists between two units
+ (e.g. foo.service requires
+ bar.service), but no ordering
+ dependency (e.g. foo.service
+ after bar.service) and both are
+ requested to start, they will be started in
+ parallel. It is a common pattern that both requirement
+ and ordering dependencies are placed between two
+ units. Also note that the majority of dependencies are
+ implicitly created and maintained by systemd. In most
+ cases it should be unnecessary to declare additional
+ dependencies manually, however it is possible to do
+ this.
+
+ Application programs and units (via
+ dependencies) may request state changes of units. In
+ systemd, these requests are encapsulated as 'jobs' and
+ maintained in a job queue. Jobs may succeed or can
+ fail, their execution is ordered based on the ordering
+ dependencies of the units they have been scheduled
+ for.
+
+ On boot systemd activates the target unit
+ default.target whose job 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.
+
+ Processes systemd spawns are placed in
+ individual Linux control groups named after the unit
+ which they belong to in the private systemd
+ hierarchy. (see cgroups.txt
+ for more information about control groups, or short
+ "cgroups"). systemd uses this to effectively keep
+ track of processes. Control group information is
+ maintained in the kernel, and is accessible via the
+ file system hierarchy (beneath
+ /sys/fs/cgroup/systemd/), or in tools
+ such as
+ ps1
+ (ps xawf -eo pid,user,cgroup,args
+ is particularly useful to list all processes and the
+ systemd units they belong to.).
+
+ systemd is compatible with the SysV init system
+ to a large degree: SysV init scripts are supported and
+ simply read as an alternative (though limited)
+ configuration file format. The SysV
+ /dev/initctl interface is
+ provided, and compatibility implementations of the
+ various SysV client tools are available. In addition to
+ that, various established Unix functionality such as
+ /etc/fstab or the
+ utmp database are
+ supported.
+
+ systemd has a minimal transaction system: if a
+ unit is requested to start up or shut down it will add
+ it and all its dependencies to a temporary
+ transaction. Then, it will verify if the transaction
+ is consistent (i.e. whether the ordering of all units
+ is cycle-free). If it is not, systemd will try to fix
+ it up, and removes non-essential jobs from the
+ transaction that might remove the loop. Also, systemd
+ tries to suppress non-essential jobs in the
+ transaction that would stop a running service. Finally
+ it is checked whether the jobs of the transaction
+ contradict jobs that have already been queued, and
+ optionally the transaction is aborted then. If all
+ worked out and the transaction is consistent and
+ minimized in its impact it is merged with all already
+ outstanding jobs and added to the run
+ queue. Effectively this means that before executing a
+ requested operation, systemd will verify that it makes
+ sense, fixing it if possible, and only failing if it
+ really cannot work.
+
+ Systemd contains native implementations of
+ various tasks that need to be executed as part of the
+ boot process. For example, it sets the host name or
+ configures the loopback network device. It also sets
+ up and mounts various API file systems, such as
+ /sys or
+ /proc.
+
+ For more information about the concepts and
+ ideas behind systemd please refer to the Original
+ Design Document.
+
+ Note that some but not all interfaces provided
+ by systemd are covered by the Interface
+ Stability Promise.
+
+
Directories
+
+
+
+ System unit directories
+
+ The systemd system
+ manager reads unit configuration from
+ various directories. Packages that
+ want to install unit files shall place
+ them in the directory returned by
+ pkg-config systemd
+ --variable=systemdsystemunitdir. Other
+ directories checked are
+ /usr/local/lib/systemd/system
+ and
+ /usr/lib/systemd/system. User
+ configuration always takes
+ precedence. pkg-config
+ systemd
+ --variable=systemdsystemconfdir
+ returns the path of the system
+ configuration directory. Packages
+ should alter the content of these
+ directories only with the
+ enable and
+ disable commands of
+ the
+ systemctl1
+ tool.
+
+
+
+
+
+ User unit directories
+
+ Similar rules apply
+ for the user unit
+ directories. However, here the XDG
+ Base Directory specification
+ is followed to find
+ units. Applications should place their
+ unit files in the directory returned
+ by pkg-config systemd
+ --variable=systemduserunitdir. Global
+ configuration is done in the directory
+ reported by pkg-config
+ systemd
+ --variable=systemduserconfdir. The
+ enable and
+ disable commands of
+ the
+ systemctl1
+ tool can handle both global (i.e. for
+ all users) and private (for one user)
+ enabling/disabling of
+ units.
+
+
+
+
+
+ SysV init scripts directory
+
+ The location of the
+ SysV init script directory varies
+ between distributions. If systemd
+ cannot find a native unit file for a
+ requested service, it will look for a
+ SysV init script of the same name
+ (with the
+ .service suffix
+ removed).
+
+
+
+
+
+ SysV runlevel link farm directory
+
+ The location of the
+ SysV runlevel link farm directory
+ varies between distributions. systemd
+ will take the link farm into account
+ when figuring out whether a service
+ shall be enabled. Note that a service
+ unit with a native unit configuration
+ file cannot be started by activating it
+ in the SysV runlevel link
+ farm.
+
+
+
+
+
+ Signals
+
+
+
+ SIGTERM
+
+ Upon receiving this
+ signal the systemd system manager
+ serializes its state, reexecutes
+ itself and deserializes the saved
+ state again. This is mostly equivalent
+ to systemctl
+ daemon-reexec.
+
+ systemd user managers will
+ start the
+ exit.target unit
+ when this signal is received. This is
+ mostly equivalent to
+ systemctl --user start
+ exit.target.
+
+
+
+ SIGINT
+
+ Upon receiving this
+ signal the systemd system manager will
+ start the
+ ctrl-alt-del.target unit. This
+ is mostly equivalent to
+ systemctl start
+ ctl-alt-del.target.
+
+ systemd user managers
+ treat this signal the same way as
+ SIGTERM.
+
+
+
+ SIGWINCH
+
+ When this signal is
+ received the systemd system manager
+ will start the
+ kbrequest.target
+ unit. This is mostly equivalent to
+ systemctl start
+ kbrequest.target.
+
+ This signal is ignored by
+ systemd user
+ managers.
+
+
+
+ SIGPWR
+
+ When this signal is
+ received the systemd manager
+ will start the
+ sigpwr.target
+ unit. This is mostly equivalent to
+ systemctl start
+ sigpwr.target.
+
+
+
+ SIGUSR1
+
+ When this signal is
+ received the systemd manager will try
+ to reconnect to the D-Bus
+ bus.
+
+
+
+ SIGUSR2
+
+ When this signal is
+ received the systemd manager will log
+ its complete state in human readable
+ form. The data logged is the same as
+ printed by systemctl
+ dump.
+
+
+
+ SIGHUP
+
+ Reloads the complete
+ daemon configuration. This is mostly
+ equivalent to systemctl
+ daemon-reload.
+
+
+
+ SIGRTMIN+0
+
+ Enters default mode, starts the
+ default.target
+ unit. This is mostly equivalent to
+ systemctl start
+ default.target.
+
+
+
+ SIGRTMIN+1
+
+ Enters rescue mode,
+ starts the
+ rescue.target
+ unit. This is mostly equivalent to
+ systemctl isolate
+ rescue.target.
+
+
+
+ SIGRTMIN+2
+
+ Enters emergency mode,
+ starts the
+ emergency.service
+ unit. This is mostly equivalent to
+ systemctl isolate
+ emergency.service.
+
+
+
+ SIGRTMIN+3
+
+ Halts the machine,
+ starts the
+ halt.target
+ unit. This is mostly equivalent to
+ systemctl start
+ halt.target.
+
+
+
+ SIGRTMIN+4
+
+ Powers off the machine,
+ starts the
+ poweroff.target
+ unit. This is mostly equivalent to
+ systemctl start
+ poweroff.target.
+
+
+
+ SIGRTMIN+5
+
+ Reboots the machine,
+ starts the
+ reboot.target
+ unit. This is mostly equivalent to
+ systemctl start
+ reboot.target.
+
+
+
+ SIGRTMIN+6
+
+ Reboots the machine via kexec,
+ starts the
+ kexec.target
+ unit. This is mostly equivalent to
+ systemctl start
+ kexec.target.
+
+
+
+ SIGRTMIN+13
+
+ Immediately halts the machine.
+
+
+
+ SIGRTMIN+14
+
+ Immediately powers off the machine.
+
+
+
+ SIGRTMIN+15
+
+ Immediately reboots the machine.
+
+
+
+ SIGRTMIN+16
+
+ Immediately reboots the machine with kexec.
+
+
+
+ SIGRTMIN+20
+
+ Enables display of
+ status messages on the console, as
+ controlled via
+ systemd.show_status=1
+ on the kernel command
+ line.
+
+
+
+ SIGRTMIN+21
+
+ Disables display of
+ status messages on the console, as
+ controlled via
+ systemd.show_status=0
+ on the kernel command
+ line.
+
+
+
+ SIGRTMIN+22
+ SIGRTMIN+23
+
+ Sets the log level to
+ debug
+ (resp. info on
+ SIGRTMIN+32), as
+ controlled via
+ systemd.log_level=debug
+ (resp. systemd.log_level=info
+ on SIGRTMIN+23) on
+ the kernel command
+ line.
+
+
+
+ SIGRTMIN+27
+ SIGRTMIN+28
+ SIGRTMIN+29
+
+ Sets the log level to
+ console
+ (resp. kmsg on
+ SIGRTMIN+28;
+ resp.syslog-or-kmsg
+ on SIGRTMIN+29), as
+ controlled via
+ systemd.log_target=console
+ (resp. systemd.log_target=kmsg
+ on SIGRTMIN+28;
+ resp
+ systemd.log_target=syslog-or-kmsg
+ on SIGRTMIN+29) on
+ the kernel command
+ line.
+
+
- Signal
+ Environment
- SIGTERM
+ $SYSTEMD_LOG_LEVEL
+ systemd reads the
+ log level from this environment
+ variable. This can be overridden with
+ .
+
+
+
+ $SYSTEMD_LOG_TARGET
+ systemd reads the
+ log target from this environment
+ variable. This can be overridden with
+ .
+
+
+
+ $SYSTEMD_LOG_COLOR
+ Controls whether
+ systemd highlights important log
+ messages. This can be overridden with
+ .
+
+
+
+ $SYSTEMD_LOG_LOCATION
+ Controls whether
+ systemd prints the code location along
+ with log messages. This can be
+ overridden with
+ .
+
+
+
+ $XDG_CONFIG_HOME
+ $XDG_CONFIG_DIRS
+ $XDG_DATA_HOME
+ $XDG_DATA_DIRS
+
+ The systemd user
+ manager uses these variables in
+ accordance to the XDG
+ Base Directory specification
+ to find its configuration.
+
+
+
+ $SYSTEMD_UNIT_PATH
+
+ Controls where systemd
+ looks for unit
+ files.
+
+
+
+ $SYSTEMD_SYSVINIT_PATH
+
+ Controls where systemd
+ looks for SysV init scripts.
+
+
+
+ $SYSTEMD_SYSVRCND_PATH
- systemd serializes its
- state, reexecutes itself and
- deserializes the saved state
- again. This is mostly equivalent to
- systemctl
- daemon-reexec.
+ Controls where systemd
+ looks for SysV init script runlevel link
+ farms.
+
+
+
+ $LISTEN_PID
+ $LISTEN_FDS
+
+ Set by systemd for
+ supervised processes during
+ socket-based activation. See
+ sd_listen_fds3
+ for more information.
+
+
+
+
+ $NOTIFY_SOCKET
+
+ Set by systemd for
+ supervised processes for status and
+ start-up completion notification. See
+ sd_notify3
+ for more information.
+
+
+ Kernel Command Line
+
+ When run as system instance systemd parses a few kernel command line arguments:
+
+
+
+ systemd.unit=
+
+ Overrides the unit to
+ activate on boot. Defaults to
+ default.target. This
+ may be used to temporarily boot into a
+ different boot unit, for example
+ rescue.target or
+ emergency.service. See
+ systemd.special7
+ for details about these
+ units.
+
+
+
+ systemd.dump_core=
+
+ Takes a boolean
+ argument. If
+ systemd dumps core when it
+ crashes. Otherwise no core dump is
+ created. Defaults to
+ .
+
+
+
+ systemd.crash_shell=
+
+ Takes a boolean
+ argument. If
+ systemd spawns a shell when it
+ crashes. Otherwise no shell is
+ spawned. Defaults to
+ , for security
+ reasons, as the shell is not protected
+ by any password
+ authentication.
+
+
+
+ systemd.crash_chvt=
+
+ Takes an integer
+ argument. If positive systemd
+ activates the specified virtual
+ terminal when it crashes. Defaults to
+ -1.
+
+
+
+ systemd.confirm_spawn=
+
+ Takes a boolean
+ argument. If
+ asks for confirmation when spawning
+ processes. Defaults to
+ .
+
+
+
+ systemd.show_status=
+
+ Takes a boolean
+ argument. If
+ shows terse service status updates on
+ the console during bootup. Defaults to
+ .
+
+
+
+ systemd.sysv_console=
+
+ Takes a boolean
+ argument. If
+ output of SysV init scripts will be
+ directed to the console. Defaults to
+ , unless
+ is passed as
+ kernel command line option in which
+ case it defaults to
+ .
+
+
+
+ systemd.log_target=
+ systemd.log_level=
+ systemd.log_color=
+ systemd.log_location=
+
+ Controls log output,
+ with the same effect as the
+ $SYSTEMD_LOG_TARGET, $SYSTEMD_LOG_LEVEL, $SYSTEMD_LOG_COLOR, $SYSTEMD_LOG_LOCATION
+ environment variables described above.
+
+
+
+ systemd.default_standard_output=
+ systemd.default_standard_error=
+ Controls default
+ standard output/error output for
+ services, with the same effect as the
+
+ resp.
+ command line arguments described
+ above.
+
+
+
+ Sockets and FIFOs
- @/org/freedesktop/systemd1/notify
+ /run/systemd/notifyDaemon status
- notification socket. This is an AF_UNIX
- datagram socket in the Linux abstract
- namespace, and is used to implement
- the daemon notification logic as
- implemented by
+ notification socket. This is an
+ AF_UNIX datagram socket and is used to
+ implement the daemon notification
+ logic as implemented by
sd_notify3.
- @/org/freedesktop/systemd1/logger
+ /run/systemd/loggerUsed internally by the
systemd-logger.service
@@ -245,21 +1082,30 @@
of spawned processes to
syslog3
or the kernel log buffer. This is an
- AF_UNIX stream socket in the Linux
- abstract namespace.
+ AF_UNIX stream
+ socket.
- @/org/freedesktop/systemd1/private
+ /run/systemd/shutdownd
+
+ Used internally by the
+ shutdown8
+ tool to implement delayed
+ shutdowns. This is an AF_UNIX datagram
+ socket.
+
+
+
+ /run/systemd/privateUsed internally as
communication channel between
systemctl1
and the systemd process. This is an
- AF_UNIX stream socket in the Linux
- abstract namespace. This interface is
- private to systemd and should not be
- used in external
+ AF_UNIX stream socket. This interface
+ is private to systemd and should not
+ be used in external
projects.
@@ -278,11 +1124,17 @@
-
See Also
+ systemctl1,
+ systemadm1,
+ systemd-notify1,
daemon7,
+ sd-daemon7,
+ systemd.unit5,
+ systemd.special5,
+ pkg-config1