Content-type: text/html; charset=UTF-8 Man page of SYSTEMD

SYSTEMD

Section: systemd (1)
Updated:
Index Return to Main Contents
 

NAME

systemd, init - systemd system and service manager  

SYNOPSIS

/lib/systemd/systemd [OPTIONS...]
init [OPTIONS...] {COMMAND}
 

DESCRIPTION

systemd is a system and service manager for Linux operating systems. When run as first process on boot (as PID 1), it acts as init system that brings up and maintains userspace services.

For compatibility with SysV, if systemd is called as init and a PID that is not 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 telinit(8) for more information.

When run as a system instance, systemd interprets the configuration file system.conf and the files in system.conf.d directories; when run as a user instance, systemd interprets the configuration file user.conf and the files in user.conf.d directories. See systemd-system.conf(5) for more information.  

OPTIONS

The following options are understood:

--test

Determine startup sequence, dump it and exit. This is an option useful for debugging only.

--dump-configuration-items

Dump understood unit configuration items. This outputs a terse but complete list of configuration items understood in unit definition files.

--unit=

Set default unit to activate on startup. If not specified, defaults to default.target.

--system, --user

For --system, tell systemd to run a system instance, even if the process ID is not 1, i.e. systemd is not run as init process. --user does the opposite, running a user instance even if the process ID is 1. 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 --system mode, but PID not 1. In practice, passing --system explicitly is only useful in conjunction with --test.

--dump-core

Enable core dumping on crash. This switch has no effect when running as user instance. This setting may also be enabled during boot on the kernel command line via the systemd.dump_core= option, see below.

--crash-vt=VT

Switch to a specific virtual console (VT) on crash. Takes a positive integer in the range 1-63, or a boolean argument. If an integer is passed, selects which VT to switch to. If yes, the VT kernel messages are written to is selected. If no, no VT switch is attempted. This switch has no effect when running as user instance. This setting may also be enabled during boot, on the kernel command line via the systemd.crash_vt= option, see below.

--crash-shell

Run a shell on crash. This switch has no effect when running as user instance. This setting may also be enabled during boot, on the kernel command line via the systemd.crash_shell= option, see below.

--crash-reboot

Automatically reboot the system on crash. This switch has no effect when running as user instance. This setting may also be enabled during boot, on the kernel command line via the systemd.crash_reboot= option, see below.

--confirm-spawn

Ask for confirmation when spawning processes. This switch has no effect when run as user instance.

--show-status=

Takes a boolean argument or the special value auto. If on, terse unit status information is shown on the console during boot-up and shutdown. If off, no such status information is shown. If set to auto behavior is similar to off, except that it is automatically switched to on, as soon as the first unit failure or significant boot delay is encountered. This switch has no effect when invoked as user instance. If specified, overrides both the kernel command line setting systemd.show_status= (see below) and the configuration file option ShowStatus=, see systemd-system.conf(5).

--log-target=

Set log target. Argument must be one of console, journal, kmsg, journal-or-kmsg, null.

--log-level=

Set log level. As argument this accepts a numerical log level or the well-known syslog(3) symbolic names (lowercase): emerg, alert, crit, err, warning, notice, info, debug.

--log-color=

Highlight important log messages. Argument is a boolean value. If the argument is omitted, it defaults to true.

--log-location=

Include code location in log messages. This is mostly relevant for debugging purposes. Argument is a boolean value. If the argument is omitted it defaults to true.

--default-standard-output=, --default-standard-error=

Sets the default output or error output for all services and sockets, respectively. That is, controls the default for StandardOutput= and StandardError= (see systemd.exec(5) for details). Takes one of inherit, null, tty, journal, journal+console, syslog, syslog+console, kmsg, kmsg+console. If the argument is omitted --default-standard-output= defaults to journal and --default-standard-error= to inherit.

--machine-id=

Override the machine-id set on the hard drive, useful for network booting or for containers. May not be set to all zeros.

--service-watchdogs=

Globally enable/disable all service watchdog timeouts and emergency actions. This setting may also be specified during boot, on the kernel command line via the systemd.service_watchdogs= option, see below. Defaults to enabled.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.
 

CONCEPTS

systemd provides a dependency system between various entities called "units" of 11 different types. 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.unit(5), however some are created automatically from other configuration, dynamically from system state or programmatically at runtime. 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, an operation timed out, or after too many restarts). 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:

1. Service units, which start and control daemons and the processes they consist of. For details, see systemd.service(5).

2. Socket units, which encapsulate local IPC or network sockets in the system, useful for socket-based activation. For details about socket units, see systemd.socket(5), for details on socket-based activation and other forms of activation, see daemon(7).

3. Target units are useful to group units, or provide well-known synchronization points during boot-up, see systemd.target(5).

4. Device units expose kernel devices in systemd and may be used to implement device-based activation. For details, see systemd.device(5).

5. Mount units control mount points in the file system, for details see systemd.mount(5).

6. Automount units provide automount capabilities, for on-demand mounting of file systems as well as parallelized boot-up. See systemd.automount(5).

7. Timer units are useful for triggering activation of other units based on timers. You may find details in systemd.timer(5).

8. Swap units are very similar to mount units and encapsulate memory swap partitions or files of the operating system. They are described in systemd.swap(5).

9. Path units may be used to activate other services when file system objects change or are modified. See systemd.path(5).

10. Slice units may be used to group units which manage system processes (such as service and scope units) in a hierarchical tree for resource management purposes. See systemd.slice(5).

11. Scope units are similar to service units, but manage foreign processes instead of starting them as well. See systemd.scope(5).

Units are named as their configuration files. Some units have special semantics. A detailed list is available in systemd.special(7).

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.special(7) 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 m[blue]cgroups.txtm[][1] 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 systemd-cgls(1) or ps(1) (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 hostname 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 m[blue]Original Design Documentm[][2].

Note that some but not all interfaces provided by systemd are covered by the m[blue]Interface Stability Promisem[][3].

Units may be generated dynamically at boot and system manager reload time, for example based on other configuration files or parameters passed on the kernel command line. For details, see systemd.generator(7).

Systems which invoke systemd in a container or initrd environment should implement the m[blue]Container Interfacem[][4] or m[blue]initrd Interfacem[][5] specifications, respectively.  

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 /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 systemctl(1) tool. Full list of directories is provided in systemd.unit(5).

User unit directories

Similar rules apply for the user unit directories. However, here the m[blue]XDG Base Directory specificationm[][6] 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 systemctl(1) tool can handle both global (i.e. for all users) and private (for one user) enabling/disabling of units. Full list of directories is provided in systemd.unit(5).

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 --job-mode=replace-irreversible.

SIGINT

Upon receiving this signal the systemd system manager will start the ctrl-alt-del.target unit. This is mostly equivalent to systemctl start ctrl-alt-del.target --job-mode=replace-irreversible. If this signal is received more than 7 times per 2s, an immediate reboot is triggered. Note that pressing Ctrl-Alt-Del on the console will trigger this signal. Hence, if a reboot is hanging, pressing Ctrl-Alt-Del more than 7 times in 2s is a relatively safe way to trigger an immediate reboot.

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 systemd-analyze 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 isolate 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 --job-mode=replace-irreversible.

SIGRTMIN+4

Powers off the machine, starts the poweroff.target unit. This is mostly equivalent to systemctl start poweroff.target --job-mode=replace-irreversible.

SIGRTMIN+5

Reboots the machine, starts the reboot.target unit. This is mostly equivalent to systemctl start reboot.target --job-mode=replace-irreversible.

SIGRTMIN+6

Reboots the machine via kexec, starts the kexec.target unit. This is mostly equivalent to systemctl start kexec.target --job-mode=replace-irreversible.

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" (or "info" on SIGRTMIN+23), as controlled via systemd.log_level=debug (or systemd.log_level=info on SIGRTMIN+23) on the kernel command line.

SIGRTMIN+24

Immediately exits the manager (only available for --user instances).

SIGRTMIN+26, SIGRTMIN+27, SIGRTMIN+28

Sets the log target to "journal-or-kmsg" (or "console" on SIGRTMIN+27, "kmsg" on SIGRTMIN+28), as controlled via systemd.log_target=journal-or-kmsg (or systemd.log_target=console on SIGRTMIN+27 or systemd.log_target=kmsg on SIGRTMIN+28) on the kernel command line.
 

ENVIRONMENT

$SYSTEMD_LOG_LEVEL

systemd reads the log level from this environment variable. This can be overridden with --log-level=.

$SYSTEMD_LOG_TARGET

systemd reads the log target from this environment variable. This can be overridden with --log-target=.

$SYSTEMD_LOG_COLOR

Controls whether systemd highlights important log messages. This can be overridden with --log-color=.

$SYSTEMD_LOG_LOCATION

Controls whether systemd prints the code location along with log messages. This can be overridden with --log-location=.

$XDG_CONFIG_HOME, $XDG_CONFIG_DIRS, $XDG_DATA_HOME, $XDG_DATA_DIRS

The systemd user manager uses these variables in accordance to the m[blue]XDG Base Directory specificationm[][6] 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

Controls where systemd looks for SysV init script runlevel link farms.

$SYSTEMD_COLORS

The value must be a boolean. Controls whether colorized output should be generated. This can be specified to override the decision that systemd makes based on $TERM and what the console is connected to.

$LISTEN_PID, $LISTEN_FDS, $LISTEN_FDNAMES

Set by systemd for supervised processes during socket-based activation. See sd_listen_fds(3) for more information.

$NOTIFY_SOCKET

Set by systemd for supervised processes for status and start-up completion notification. See sd_notify(3) for more information.
 

KERNEL COMMAND LINE

When run as system instance systemd parses a number of kernel command line arguments[7]:

systemd.unit=, rd.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.special(7) for details about these units. The option prefixed with "rd." is honored only in the initial RAM disk (initrd), while the one that is not prefixed only in the main system.

systemd.dump_core

Takes a boolean argument or enables the option if specified without an argument. If enabled, the systemd manager (PID 1) dumps core when it crashes. Otherwise, no core dump is created. Defaults to enabled.

systemd.crash_chvt

Takes a positive integer, or a boolean argument. Can be also specified without an argument, with the same effect as a positive boolean. If a positive integer (in the range 1-63) is specified, the system manager (PID 1) will activate the specified virtual terminal (VT) when it crashes. Defaults to disabled, meaning that no such switch is attempted. If set to enabled, the VT the kernel messages are written to is selected.

systemd.crash_shell

Takes a boolean argument or enables the option if specified without an argument. If enabled, the system manager (PID 1) spawns a shell when it crashes, after a 10s delay. Otherwise, no shell is spawned. Defaults to disabled, for security reasons, as the shell is not protected by password authentication.

systemd.crash_reboot

Takes a boolean argument or enables the option if specified without an argument. If enabled, the system manager (PID 1) will reboot the machine automatically when it crashes, after a 10s delay. Otherwise, the system will hang indefinitely. Defaults to disabled, in order to avoid a reboot loop. If combined with systemd.crash_shell, the system is rebooted after the shell exits.

systemd.confirm_spawn

Takes a boolean argument or a path to the virtual console where the confirmation messages should be emitted. Can be also specified without an argument, with the same effect as a positive boolean. If enabled, the system manager (PID 1) asks for confirmation when spawning processes using /dev/console. If a path or a console name (such as "ttyS0") is provided, the virtual console pointed to by this path or described by the give name will be used instead. Defaults to disabled.

systemd.service_watchdogs=

Takes a boolean argument. If disabled, all service runtime watchdogs (WatchdogSec=) and emergency actions (e.g. OnFailure= or StartLimitAction=) are ignored by the system manager (PID 1); see systemd.service(5). Defaults to enabled, i.e. watchdogs and failure actions are processed normally. The hardware watchdog is not affected by this option.

systemd.show_status

Takes a boolean argument or the constant auto. Can be also specified without an argument, with the same effect as a positive boolean. If enabled, the systemd manager (PID 1) shows terse service status updates on the console during bootup. auto behaves like false until a unit fails or there is a significant delay in boot. Defaults to enabled, unless quiet is passed as kernel command line option, in which case it defaults to auto. If specified overrides the system manager configuration file option ShowStatus=, see systemd-system.conf(5). However, the process command line option --show-status= takes precedence over both this kernel command line option and the configuration file option.

systemd.log_target=, systemd.log_level=, systemd.log_location=, systemd.log_color

Controls log output, with the same effect as the $SYSTEMD_LOG_TARGET, $SYSTEMD_LOG_LEVEL, $SYSTEMD_LOG_LOCATION, $SYSTEMD_LOG_COLOR environment variables described above. systemd.log_color can be specified without an argument, with the same effect as a positive boolean.

systemd.default_standard_output=, systemd.default_standard_error=

Controls default standard output and error output for services, with the same effect as the --default-standard-output= and --default-standard-error= command line arguments described above, respectively.

systemd.setenv=

Takes a string argument in the form VARIABLE=VALUE. May be used to set default environment variables to add to forked child processes. May be used more than once to set multiple variables.

systemd.machine_id=

Takes a 32 character hex value to be used for setting the machine-id. Intended mostly for network booting where the same machine-id is desired for every boot.

systemd.unified_cgroup_hierarchy

When specified without an argument or with a true argument, enables the usage of m[blue]unified cgroup hierarchym[][8] (a.k.a. cgroups-v2). When specified with a false argument, fall back to hybrid or full legacy cgroup hierarchy.

If this option is not specified, the default behaviour is determined during compilation (the --with-default-hierarchy= option). If the kernel does not support unified cgroup hierarchy, the legacy hierarchy will be used even if this option is specified.

systemd.legacy_systemd_cgroup_controller

Takes effect if the full unified cgroup hierarchy is not used (see previous option). When specified without an argument or with a true argument, disables the use of "hybrid" cgroup hierarchy (i.e. a cgroups-v2 tree used for systemd, and m[blue]legacy cgroup hierarchym[][9], a.k.a. cgroups-v1, for other controllers), and forces a full "legacy" mode. When specified with a false argument, enables the use of "hybrid" hierarchy.

If this option is not specified, the default behaviour is determined during compilation (the --with-default-hierarchy= option). If the kernel does not support unified cgroup hierarchy, the legacy hierarchy will be used even if this option is specified.

quiet

Turn off status output at boot, much like systemd.show_status=false would. Note that this option is also read by the kernel itself and disables kernel log output. Passing this option hence turns off the usual output from both the system manager and the kernel.

debug

Turn on debugging output. This is equivalent to systemd.log_level=debug. Note that this option is also read by the kernel itself and enables kernel debug output. Passing this option hence turns on the debug output from both the system manager and the kernel.

emergency, rd.emergency, -b

Boot into emergency mode. This is equivalent to systemd.unit=emergency.target or rd.systemd.unit=emergency.target, respectively, and provided for compatibility reasons and to be easier to type.

rescue, rd.rescue, single, s, S, 1

Boot into rescue mode. This is equivalent to systemd.unit=rescue.target or rd.systemd.unit=rescue.target, respectively, and provided for compatibility reasons and to be easier to type.

2, 3, 4, 5

Boot into the specified legacy SysV runlevel. These are equivalent to systemd.unit=runlevel2.target, systemd.unit=runlevel3.target, systemd.unit=runlevel4.target, and systemd.unit=runlevel5.target, respectively, and provided for compatibility reasons and to be easier to type.

locale.LANG=, locale.LANGUAGE=, locale.LC_CTYPE=, locale.LC_NUMERIC=, locale.LC_TIME=, locale.LC_COLLATE=, locale.LC_MONETARY=, locale.LC_MESSAGES=, locale.LC_PAPER=, locale.LC_NAME=, locale.LC_ADDRESS=, locale.LC_TELEPHONE=, locale.LC_MEASUREMENT=, locale.LC_IDENTIFICATION=

Set the system locale to use. This overrides the settings in /etc/locale.conf. For more information, see locale.conf(5) and locale(7).

For other kernel command line parameters understood by components of the core OS, please refer to kernel-command-line(7).  

SOCKETS AND FIFOS

/run/systemd/notify

Daemon status notification socket. This is an AF_UNIX datagram socket and is used to implement the daemon notification logic as implemented by sd_notify(3).

/run/systemd/private

Used internally as communication channel between systemctl(1) and the systemd process. This is an AF_UNIX stream socket. This interface is private to systemd and should not be used in external projects.

/dev/initctl

Limited compatibility support for the SysV client interface, as implemented by the systemd-initctl.service unit. This is a named pipe in the file system. This interface is obsolete and should not be used in new applications.
 

SEE ALSO

The m[blue]systemd Homepagem[][10], systemd-system.conf(5), locale.conf(5), systemctl(1), journalctl(1), systemd-notify(1), daemon(7), sd-daemon(3), systemd.unit(5), systemd.special(5), pkg-config(1), kernel-command-line(7), bootup(7), systemd.directives(7)  

NOTES

1.
cgroups.txt
https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt
2.
Original Design Document
http://0pointer.de/blog/projects/systemd.html
3.
Interface Stability Promise
https://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise
4.
Container Interface
https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface
5.
initrd Interface
https://www.freedesktop.org/wiki/Software/systemd/InitrdInterface
6.
XDG Base Directory specification
http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
7.
If run inside a Linux container these arguments may be passed as command line arguments to systemd itself, next to any of the command line options listed in the Options section above. If run outside of Linux containers, these arguments are parsed from /proc/cmdline instead.
8.
unified cgroup hierarchy
https://www.kernel.org/doc/Documentation/cgroup-v2.txt
9.
legacy cgroup hierarchy
https://www.kernel.org/doc/Documentation/cgroup-v1/
10.
systemd Homepage
https://www.freedesktop.org/wiki/Software/systemd/


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONCEPTS
DIRECTORIES
SIGNALS
ENVIRONMENT
KERNEL COMMAND LINE
SOCKETS AND FIFOS
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:32 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.MOUNT

SYSTEMD.MOUNT

Section: systemd.mount (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.mount - Mount unit configuration  

SYNOPSIS

mount.mount  

DESCRIPTION

A unit configuration file whose name ends in ".mount" encodes information about a file system mount point controlled and supervised by systemd.

This man page lists the configuration options specific to this unit type. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The mount specific configuration options are configured in the [Mount] section.

Additional options are listed in systemd.exec(5), which define the execution environment the mount(8) program is executed in, and in systemd.kill(5), which define the way the processes are terminated, and in systemd.resource-control(5), which configure resource control settings for the processes of the service.

Note that the options User= and Group= are not useful for mount units. systemd passes two parameters to mount(8); the values of What= and Where=. When invoked in this way, mount(8) does not read any options from /etc/fstab, and must be run as UID 0.

Mount units must be named after the mount point directories they control. Example: the mount point /home/lennart must be configured in a unit file home-lennart.mount. For details about the escaping logic used to convert a file system path to a unit name, see systemd.unit(5). Note that mount units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to it.

Optionally, a mount unit may be accompanied by an automount unit, to allow on-demand or parallelized mounting. See systemd.automount(5).

Mount points created at runtime (independently of unit files or /etc/fstab) will be monitored by systemd and appear like any other mount unit in systemd. See /proc/self/mountinfo description in proc(5).

Some file systems have special semantics as API file systems for kernel-to-userspace and userspace-to-userspace interfaces. Some of them may not be changed via mount units, and cannot be disabled. For a longer discussion see m[blue]API File Systemsm[][1].  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• If a mount unit is beneath another mount unit in the file system hierarchy, both a requirement dependency and an ordering dependency between both units are created automatically.

• Block device backed file systems automatically gain BindsTo= and After= type dependencies on the device unit encapsulating the block device (see below).

• If traditional file system quota is enabled for a mount unit, automatic Wants= and Before= dependencies on systemd-quotacheck.service and quotaon.service are added.

• Additional implicit dependencies may be added as result of execution and resource control parameters as documented in systemd.exec(5) and systemd.resource-control(5).
 

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• All mount units acquire automatic Before= and Conflicts= on umount.target in order to be stopped during shutdown.

• Mount units referring to local file systems automatically gain an After= dependency on local-fs-pre.target.

• Network mount units automatically acquire After= dependencies on remote-fs-pre.target, network.target and network-online.target. Towards the latter a Wants= unit is added as well.

Mount units referring to local and network file systems are distinguished by their file system type specification. In some cases this is not sufficient (for example network block device based mounts, such as iSCSI), in which case _netdev may be added to the mount option string of the unit, which forces systemd to consider the mount unit a network mount.  

FSTAB

Mount units may either be configured via unit files, or via /etc/fstab (see fstab(5) for details). Mounts listed in /etc/fstab will be converted into native units dynamically at boot and when the configuration of the system manager is reloaded. In general, configuring mount points through /etc/fstab is the preferred approach. See systemd-fstab-generator(8) for details about the conversion.

The NFS mount option bg for NFS background mounts as documented in nfs(5) is detected by systemd-fstab-generator and the options are transformed so that systemd fulfills the job-control implications of that option. Specifically systemd-fstab-generator acts as though "x-systemd.mount-timout=infinity,retry=10000" was prepended to the option list, and "fg,nofail" was appended. Depending on specific requirements, it may be appropriate to provide some of these options explicitly, or to make use of the "x-systemd.automount" option described below instead of using "bg".

When reading /etc/fstab a few special mount options are understood by systemd which influence how dependencies are created for mount points. systemd will create a dependency of type Wants= or Requires (see option nofail below), from either local-fs.target or remote-fs.target, depending whether the file system is local or remote.

x-systemd.requires=

Configures a Requires= and an After= dependency between the created mount unit and another systemd unit, such as a device or mount unit. The argument should be a unit name, or an absolute path to a device node or mount point. This option may be specified more than once. This option is particularly useful for mount point declarations that need an additional device to be around (such as an external journal device for journal file systems) or an additional mount to be in place (such as an overlay file system that merges multiple mount points). See After= and Requires= in systemd.unit(5) for details.

x-systemd.before=, x-systemd.after=

Configures a Before= dependency or After= between the created mount unit and another systemd unit, such as a mount unit. The argument should be a unit name or an absolute path to a mount point. This option may be specified more than once. This option is particularly useful for mount point declarations with nofail option that are mounted asynchronously but need to be mounted before or after some unit start, for example, before local-fs.target unit. See Before= and After= in systemd.unit(5) for details.

x-systemd.requires-mounts-for=

Configures a RequiresMountsFor= dependency between the created mount unit and other mount units. The argument must be an absolute path. This option may be specified more than once. See RequiresMountsFor= in systemd.unit(5) for details.

x-systemd.device-bound

The block device backed file system will be upgraded to BindsTo= dependency. This option is only useful when mounting file systems manually with mount(8) as the default dependency in this case is Requires=. This option is already implied by entries in /etc/fstab or by mount units.

x-systemd.automount

An automount unit will be created for the file system. See systemd.automount(5) for details.

x-systemd.idle-timeout=

Configures the idle timeout of the automount unit. See TimeoutIdleSec= in systemd.automount(5) for details.

x-systemd.device-timeout=

Configure how long systemd should wait for a device to show up before giving up on an entry from /etc/fstab. Specify a time in seconds or explicitly append a unit such as "s", "min", "h", "ms".

Note that this option can only be used in /etc/fstab, and will be ignored when part of the Options= setting in a unit file.

x-systemd.mount-timeout=

Configure how long systemd should wait for the mount command to finish before giving up on an entry from /etc/fstab. Specify a time in seconds or explicitly append a unit such as "s", "min", "h", "ms".

Note that this option can only be used in /etc/fstab, and will be ignored when part of the Options= setting in a unit file.

See TimeoutSec= below for details.

x-systemd.makefs

The file system or swap structure will be intialized on the device. If the device is not "empty", i.e. it contains any signature, the operation will be skipped. It is hence expected that this option remains set even after the device has been initalized.

Note that this option can only be used in /etc/fstab, and will be ignored when part of the Options= setting in a unit file.

See systemd-makefs@.service(8).

wipefs(8) may be used to remove any signatures from a block device to force x-systemd.makefs to reinitialize the device.

x-systemd.growfs

The file system will be grown to occupy the full block device. If the file system is already at maximum size, no action will be performed. It is hence expected that this option remains set even after the file system has been grown. Only certain file system types are supported, see systemd-makefs@.service(8) for details.

Note that this option can only be used in /etc/fstab, and will be ignored when part of the Options= setting in a unit file.

_netdev

Normally the file system type is used to determine if a mount is a "network mount", i.e. if it should only be started after the network is available. Using this option overrides this detection and specifies that the mount requires network.

Network mount units are ordered between remote-fs-pre.target and remote-fs.target, instead of local-fs-pre.target and local-fs.target. They also pull in network-online.target and are ordered after it and network.target.

noauto, auto

With noauto, the mount unit will not be added as a dependency for local-fs.target or remote-fs.target. This means that it will not be mounted automatically during boot, unless it is pulled in by some other unit. The auto option has the opposite meaning and is the default. Note that the noauto option has an effect on the mount unit itself only --- if x-systemd.automount is used (see above), then the matching automount unit will still be pulled in by these targets.

nofail

With nofail, this mount will be only wanted, not required, by local-fs.target or remote-fs.target. This means that the boot will continue even if this mount point is not mounted successfully.

x-initrd.mount

An additional filesystem to be mounted in the initramfs. See initrd-fs.target description in systemd.special(7).

If a mount point is configured in both /etc/fstab and a unit file that is stored below /usr, the former will take precedence. If the unit file is stored below /etc, it will take precedence. This means: native unit files take precedence over traditional configuration files, but this is superseded by the rule that configuration in /etc will always take precedence over configuration in /usr.  

OPTIONS

Mount files must include a [Mount] section, which carries information about the file system mount points 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.exec(5) and systemd.kill(5). The options specific to the [Mount] section of mount units are the following:

What=

Takes an absolute path of a device node, file or other resource to mount. See mount(8) for details. If this refers to a device node, a dependency on the respective device unit is automatically created. (See systemd.device(5) for more information.) This option is mandatory. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as "%%".

Where=

Takes an absolute path of a directory for the mount point; in particular, the destination cannot be a symbolic link. If the mount point does not exist at the time of mounting, it is created. This string must be reflected in the unit filename. (See above.) This option is mandatory.

Type=

Takes a string for the file system type. See mount(8) for details. This setting is optional.

Options=

Mount options to use when mounting. This takes a comma-separated list of options. This setting is optional. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as "%%".

SloppyOptions=

Takes a boolean argument. If true, parsing of the options specified in Options= is relaxed, and unknown mount options are tolerated. This corresponds with mount(8)'s -s switch. Defaults to off.

LazyUnmount=

Takes a boolean argument. If true, detach the filesystem from the filesystem hierarchy at time of the unmount operation, and clean up all references to the filesystem as soon as they are not busy anymore. This corresponds with umount(8)'s -l switch. Defaults to off.

ForceUnmount=

Takes a boolean argument. If true, force an unmount (in case of an unreachable NFS system). This corresponds with umount(8)'s -f switch. Defaults to off.

DirectoryMode=

Directories of mount points (and any parent directories) are automatically created if needed. This option specifies the file system access mode used when creating these directories. Takes an access mode in octal notation. Defaults to 0755.

TimeoutSec=

Configures the time to wait for the mount command to finish. If a command does not exit within the configured time, the mount will be considered failed and be shut down again. All commands still running will be terminated forcibly via SIGTERM, and after another delay of this time with SIGKILL. (See KillMode= in systemd.kill(5).) Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout logic. The default value is set from the manager configuration file's DefaultTimeoutStartSec= variable.

Check systemd.exec(5) and systemd.kill(5) for more settings.  

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), systemd.exec(5), systemd.kill(5), systemd.resource-control(5), systemd.service(5), systemd.device(5), proc(5), mount(8), systemd-fstab-generator(8), systemd.directives(7)  

NOTES

1.
API File Systems
https://www.freedesktop.org/wiki/Software/systemd/APIFileSystems


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
FSTAB
OPTIONS
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:53 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.UNIT

SYSTEMD.UNIT

Section: systemd.unit (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.unit - Unit configuration  

SYNOPSIS

service.service, socket.socket, device.device, mount.mount, automount.automount, swap.swap, target.target, path.path, timer.timer, slice.slice, scope.scope

/etc/systemd/system/*
/run/systemd/system/*
/lib/systemd/system/*
...
    

~/.config/systemd/user/*
/etc/systemd/user/*
$XDG_RUNTIME_DIR/systemd/user/*
/run/systemd/user/*
~/.local/share/systemd/user/*
/usr/lib/systemd/user/*
...
    
 

DESCRIPTION

A unit configuration file encodes information about a service, a socket, a device, a mount point, an automount point, a swap file or partition, a start-up target, a watched file system path, a timer controlled and supervised by systemd(1), a resource management slice or a group of externally created processes. The syntax is inspired by m[blue]XDG Desktop Entry Specificationm[][1] .desktop files, which are in turn inspired by Microsoft Windows .ini files.

This man page lists the common configuration options of all the unit types. These options need to be configured in the [Unit] or [Install] sections of the unit files.

In addition to the generic [Unit] and [Install] sections described here, each unit may have a type-specific section, e.g. [Service] for a service unit. See the respective man pages for more information: systemd.service(5), systemd.socket(5), systemd.device(5), systemd.mount(5), systemd.automount(5), systemd.swap(5), systemd.target(5), systemd.path(5), systemd.timer(5), systemd.slice(5), systemd.scope(5).

Various settings are allowed to be specified more than once, in which case the interpretation depends on the setting. Often, multiple settings form a list, and setting to an empty value "resets", which means that previous assignments are ignored. When this is allowed, it is mentioned in the description of the setting. Note that using multiple assignments to the same value makes the unit file incompatible with parsers for the XDG .desktop file format.

Unit files are loaded from a set of paths determined during compilation, described in the next section.

Unit files may contain additional options on top of those listed here. If systemd encounters an unknown option, it will write a warning log message but continue loading the unit. If an option or section name is prefixed with X-, it is ignored completely by systemd. Options within an ignored section do not need the prefix. Applications may use this to include additional information in the unit files.

Boolean arguments used in unit files can be written in various formats. For positive settings the strings 1, yes, true and on are equivalent. For negative settings, the strings 0, no, false and off are equivalent.

Time span values encoded in unit files can be written in various formats. A stand-alone number specifies a time in seconds. If suffixed with a time unit, the unit is honored. A concatenation of multiple values with units is supported, in which case the values are added up. Example: "50" refers to 50 seconds; "2min 200ms" refers to 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units are understood: "s", "min", "h", "d", "w", "ms", "us". For details see systemd.time(7).

Empty lines and lines starting with "#" or ";" are ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the following line while reading and the backslash is replaced by a space character. This may be used to wrap long lines.

Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name in one of the unit search paths. For example, systemd-networkd.service has the alias dbus-org.freedesktop.network1.service, created during installation as the symlink /lib/systemd/system/dbus-org.freedesktop.network1.service. In addition, unit files may specify aliases through the Alias= directive in the [Install] section; those aliases are only effective when the unit is enabled. When the unit is enabled, symlinks will be created for those names, and removed when the unit is disabled. For example, reboot.target specifies Alias=ctrl-alt-del.target, so when enabled it will be invoked whenever CTRL+ALT+DEL is pressed. Alias names may be used in commands like enable, disable, start, stop, status, ..., and in unit dependency directives Wants=, Requires=, Before=, After=, ..., with the limitation that aliases specified through Alias= are only effective when the unit is enabled. Aliases cannot be used with the preset command.

Along with a unit file foo.service, the directory foo.service.wants/ may exist. All unit files symlinked from such a directory are implicitly added as dependencies of type Wants= to the unit. This is useful to hook units into the start-up of other units, without having to modify their unit files. For details about the semantics of Wants=, see below. The preferred way to create symlinks in the .wants/ directory of a unit file is with the enable command of the systemctl(1) tool which reads information from the [Install] section of unit files (see below). A similar functionality exists for Requires= type dependencies as well, the directory suffix is .requires/ in this case.

Along with a unit file foo.service, a "drop-in" directory foo.service.d/ may exist. All files with the suffix ".conf" from this directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings for a unit, without having to modify unit files. Each drop-in file must have appropriate section headers. Note that for instantiated units, this logic will first look for the instance ".d/" subdirectory and read its ".conf" files, followed by the template ".d/" subdirectory and the ".conf" files there.

In addition to /etc/systemd/system, the drop-in ".d" directories for system services can be placed in /lib/systemd/system or /run/systemd/system directories. Drop-in files in /etc take precedence over those in /run which in turn take precedence over those in /lib. Drop-in files under any of these directories take precedence over unit files wherever located. Multiple drop-in files with different names are applied in lexicographic order, regardless of which of the directories they reside in.

Note that while systemd offers a flexible dependency system between units it is recommended to use this functionality only sparingly and instead rely on techniques such as bus-based or socket-based activation which make dependencies implicit, resulting in a both simpler and more flexible system.

Optionally, units may be instantiated from a template file at runtime. This allows creation of multiple units from a single configuration file. If systemd looks for a unit configuration file, it will first search for the literal unit name in the file system. If that yields no success and the unit name contains an "@" character, systemd will look for a unit template that shares the same name but with the instance string (i.e. the part between the "@" character and the suffix) removed. Example: if a service getty@tty3.service is requested and no file by that name is found, systemd will look for getty@.service and instantiate a service from that configuration file if it is found.

To refer to the instance string from within the configuration file you may use the special "%i" specifier in many of the configuration options. See below for details.

If a unit file is empty (i.e. has the file size 0) or is symlinked to /dev/null, its configuration will not be loaded and it appears with a load state of "masked", and cannot be activated. Use this as an effective way to fully disable a unit, making it impossible to start it even manually.

The unit file format is covered by the m[blue]Interface Stability Promisem[][2].  

STRING ESCAPING FOR INCLUSION IN UNIT NAMES

Sometimes it is useful to convert arbitrary strings into unit names. To facilitate this, a method of string escaping is used, in order to map strings containing arbitrary byte values (except NUL) into valid unit names and their restricted character set. A common special case are unit names that reflect paths to objects in the file system hierarchy. Example: a device unit dev-sda.device refers to a device with the device node /dev/sda in the file system.

The escaping algorithm operates as follows: given a string, any "/" character is replaced by "-", and all other characters which are not ASCII alphanumerics or "_" are replaced by C-style "\x2d" escapes. In addition, "." is replaced with such a C-style escape when it would appear as the first character in the escaped string.

When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the root directory "/" is encoded as single dash "-". In addition, any leading, trailing or duplicate "/" characters are removed from the string before transformation. Example: /foo//bar/baz/ becomes "foo-bar-baz".

This escaping is fully reversible, as long as it is known whether the escaped string was a path (the unescaping results are different for paths and non-path strings). The systemd-escape(1) command may be used to apply and reverse escaping on arbitrary strings. Use systemd-escape --path to escape path strings, and systemd-escape without --path otherwise.  

IMPLICIT DEPENDENCIES

A number of unit dependencies are implicitly established, depending on unit type and unit configuration. These implicit dependencies can make unit configuration file cleaner. For the implicit dependencies in each unit type, please refer to section "Implicit Dependencies" in respective man pages.

For example, service units with Type=dbus automatically acquire dependencies of type Requires= and After= on dbus.socket. See systemd.service(5) for details.  

DEFAULT DEPENDENCIES

Default dependencies are similar to implicit dependencies, but can be turned on and off by setting DefaultDependencies= to yes (the default) and no, while implicit dependencies are always in effect. See section "Default Dependencies" in respective man pages for the effect of enabling DefaultDependencies= in each unit types.

For example, target units will complement all configured dependencies of type Wants= or Requires= with dependencies of type After= unless DefaultDependencies=no is set in the specified units. See systemd.target(5) for details. Note that this behavior can be turned off by setting DefaultDependencies=no.  

UNIT FILE LOAD PATH

Unit files are loaded from a set of paths determined during compilation, described in the two tables below. Unit files found in directories listed earlier override files with the same name in directories lower in the list.

When the variable $SYSTEMD_UNIT_PATH is set, the contents of this variable overrides the unit load path. If $SYSTEMD_UNIT_PATH ends with an empty component (":"), the usual unit load path will be appended to the contents of the variable.


Table 1.  Load path when running in system mode (--system).

Path Description
/etc/systemd/system Local configuration
/run/systemd/system Runtime units
/lib/systemd/system Units of installed packages


Table 2.  Load path when running in user mode (--user).

Path Description
$XDG_CONFIG_HOME/systemd/user User configuration (only used when $XDG_CONFIG_HOME is set)
$HOME/.config/systemd/user User configuration (only used when $XDG_CONFIG_HOME is not set)
/etc/systemd/user Local configuration
$XDG_RUNTIME_DIR/systemd/user Runtime units (only used when $XDG_RUNTIME_DIR is set)
/run/systemd/user Runtime units
$XDG_DATA_HOME/systemd/user Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)
$HOME/.local/share/systemd/user Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)
/usr/lib/systemd/user Units of packages that have been installed system-wide

Additional units might be loaded into systemd ("linked") from directories not on the unit load path. See the link command for systemctl(1). Also, some units are dynamically created via a systemd.generator(7).  

UNIT GARBAGE COLLECTION

The system and service manager loads a unit's configuration automatically when a unit is referenced for the first time. It will automatically unload the unit configuration and state again when the unit is not needed anymore ("garbage collection"). A unit may be referenced through a number of different mechanisms:

1. Another loaded unit references it with a dependency such as After=, Wants=, ...

2. The unit is currently starting, running, reloading or stopping.

3. The unit is currently in the failed state. (But see below.)

4. A job for the unit is pending.

5. The unit is pinned by an active IPC client program.

6. The unit is a special "perpetual" unit that is always active and loaded. Examples for perpetual units are the root mount unit -.mount or the scope unit init.scope that the service manager itself lives in.

7. The unit has running processes associated with it.

The garbage collection logic may be altered with the CollectMode= option, which allows configuration whether automatic unloading of units that are in failed state is permissible, see below.

Note that when a unit's configuration and state is unloaded, all execution results, such as exit codes, exit signals, resource consumption and other statistics are lost, except for what is stored in the log subsystem.

Use systemctl daemon-reload or an equivalent command to reload unit configuration while the unit is already loaded. In this case all configuration settings are flushed out and replaced with the new configuration (which however might not be in effect immediately), however all runtime state is saved/restored.  

[UNIT] SECTION OPTIONS

The unit file may include a [Unit] section, which carries generic information about the unit that is not dependent on the type of unit:

Description=

A free-form string describing the unit. This is intended for use in UIs to show descriptive information along with the unit name. The description should contain a name that means something to the end user. "Apache2 Web Server" is a good example. Bad examples are "high-performance light-weight HTTP server" (too generic) or "Apache2" (too specific and meaningless for people who do not know Apache).

Documentation=

A space-separated list of URIs referencing documentation for this unit or its configuration. Accepted are only URIs of the types "http://", "https://", "file:", "info:", "man:". For more information about the syntax of these URIs, see uri(7). The URIs should be listed in order of relevance, starting with the most relevant. It is a good idea to first reference documentation that explains what the unit's purpose is, followed by how it is configured, followed by any other related documentation. This option may be specified more than once, in which case the specified list of URIs is merged. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect.

Requires=

Configures requirement dependencies on other units. If this unit gets activated, the units listed here will be activated as well. If one of the other units fails to activate, and an ordering dependency After= on the failing unit is set, this unit will not be started. Besides, with or without specifying After=, this unit will be stopped if one of the other units is explicitly stopped. This option may be specified more than once or multiple space-separated units may be specified in one option in which case requirement dependencies for all listed names will be created. Note that requirement dependencies do not influence the order in which services are started or stopped. This has to be configured independently with the After= or Before= options. If a unit foo.service requires a unit bar.service as configured with Requires= and no ordering is configured with After= or Before=, then both units will be started simultaneously and without any delay between them if foo.service is activated. Often, it is a better choice to use Wants= instead of Requires= in order to achieve a system that is more robust when dealing with failing services.

Note that this dependency type does not imply that the other unit always has to be in active state when this unit is running. Specifically: failing condition checks (such as ConditionPathExists=, ConditionPathIsSymbolicLink=, ... --- see below) do not cause the start job of a unit with a Requires= dependency on it to fail. Also, some unit types may deactivate on their own (for example, a service process may decide to exit cleanly, or a device may be unplugged by the user), which is not propagated to units having a Requires= dependency. Use the BindsTo= dependency type together with After= to ensure that a unit may never be in active state without a specific other unit also in active state (see below).

Note that dependencies of this type may also be configured outside of the unit configuration file by adding a symlink to a .requires/ directory accompanying the unit file. For details, see above.

Requisite=

Similar to Requires=. However, if the units listed here are not started already, they will not be started and the transaction will fail immediately.

When Requisite=b.service is used on a.service, this dependency will show as RequisiteOf=a.service in property listing of b.service. RequisiteOf= dependency cannot be specified directly.

Wants=

A weaker version of Requires=. Units listed in this option will be started if the configuring unit is. However, if the listed units fail to start or cannot be added to the transaction, this has no impact on the validity of the transaction as a whole. This is the recommended way to hook start-up of one unit to the start-up of another unit.

Note that dependencies of this type may also be configured outside of the unit configuration file by adding symlinks to a .wants/ directory accompanying the unit file. For details, see above.

BindsTo=

Configures requirement dependencies, very similar in style to Requires=. However, this dependency type is stronger: in addition to the effect of Requires= it declares that if the unit bound to is stopped, this unit will be stopped too. This means a unit bound to another unit that suddenly enters inactive state will be stopped too. Units can suddenly, unexpectedly enter inactive state for different reasons: the main process of a service unit might terminate on its own choice, the backing device of a device unit might be unplugged or the mount point of a mount unit might be unmounted without involvement of the system and service manager.

When used in conjunction with After= on the same unit the behaviour of BindsTo= is even stronger. In this case, the unit bound to strictly has to be in active state for this unit to also be in active state. This not only means a unit bound to another unit that suddenly enters inactive state, but also one that is bound to another unit that gets skipped due to a failed condition check (such as ConditionPathExists=, ConditionPathIsSymbolicLink=, ... --- see below) will be stopped, should it be running. Hence, in many cases it is best to combine BindsTo= with After=.

When BindsTo=b.service is used on a.service, this dependency will show as BoundBy=a.service in property listing of b.service. BoundBy= dependency cannot be specified directly.

PartOf=

Configures dependencies similar to Requires=, but limited to stopping and restarting of units. When systemd stops or restarts the units listed here, the action is propagated to this unit. Note that this is a one-way dependency --- changes to this unit do not affect the listed units.

When PartOf=b.service is used on a.service, this dependency will show as ConsistsOf=a.service in property listing of b.service. ConsistsOf= dependency cannot be specified directly.

Conflicts=

A space-separated list of unit names. Configures negative requirement dependencies. If a unit has a Conflicts= setting on another unit, starting the former will stop the latter and vice versa. Note that this setting is independent of and orthogonal to the After= and Before= ordering dependencies.

If a unit A that conflicts with a unit B is scheduled to be started at the same time as B, the transaction will either fail (in case both are required part of the transaction) or be modified to be fixed (in case one or both jobs are not a required part of the transaction). In the latter case, the job that is not the required will be removed, or in case both are not required, the unit that conflicts will be started and the unit that is conflicted is stopped.

Before=, After=

These two settings expect a space-separated list of unit names. They configure ordering dependencies between units. If a unit foo.service contains a setting Before=bar.service and both units are being started, bar.service's start-up is delayed until foo.service has finished starting up. Note that this setting is independent of and orthogonal to the requirement dependencies as configured by Requires=, Wants= or BindsTo=. It is a common pattern to include a unit name in both the After= and Requires= options, in which case the unit listed will be started before the unit that is configured with these options. This option may be specified more than once, in which case ordering dependencies for all listed names are created. After= is the inverse of Before=, i.e. while After= ensures that the configured unit is started after the listed unit finished starting up, Before= ensures the opposite, that the configured unit is fully started up before the listed unit is started. Note that when two units with an ordering dependency between them are shut down, the inverse of the start-up order is applied. i.e. if a unit is configured with After= on another unit, the former is stopped before the latter if both are shut down. Given two units with any ordering dependency between them, if one unit is shut down and the other is started up, the shutdown is ordered before the start-up. It doesn't matter if the ordering dependency is After= or Before=, in this case. It also doesn't matter which of the two is shut down, as long as one is shut down and the other is started up. The shutdown is ordered before the start-up in all cases. If two units have no ordering dependencies between them, they are shut down or started up simultaneously, and no ordering takes place. It depends on the unit type when precisely a unit has finished starting up. Most importantly, for service units start-up is considered completed for the purpose of Before=/After= when all its configured start-up commands have been invoked and they either failed or reported start-up success.

OnFailure=

A space-separated list of one or more units that are activated when this unit enters the "failed" state. A service unit using Restart= enters the failed state only after the start limits are reached.

PropagatesReloadTo=, ReloadPropagatedFrom=

A space-separated list of one or more units where reload requests on this unit will be propagated to, or reload requests on the other unit will be propagated to this unit, respectively. Issuing a reload request on a unit will automatically also enqueue a reload request on all units that the reload request shall be propagated to via these two settings.

JoinsNamespaceOf=

For units that start processes (such as service units), lists one or more other units whose network and/or temporary file namespace to join. This only applies to unit types which support the PrivateNetwork= and PrivateTmp= directives (see systemd.exec(5) for details). If a unit that has this setting set is started, its processes will see the same /tmp, /var/tmp and network namespace as one listed unit that is started. If multiple listed units are already started, it is not defined which namespace is joined. Note that this setting only has an effect if PrivateNetwork= and/or PrivateTmp= is enabled for both the unit that joins the namespace and the unit whose namespace is joined.

RequiresMountsFor=

Takes a space-separated list of absolute paths. Automatically adds dependencies of type Requires= and After= for all mount units required to access the specified path.

Mount points marked with noauto are not mounted automatically through local-fs.target, but are still honored for the purposes of this option, i.e. they will be pulled in by this unit.

OnFailureJobMode=

Takes a value of "fail", "replace", "replace-irreversibly", "isolate", "flush", "ignore-dependencies" or "ignore-requirements". Defaults to "replace". Specifies how the units listed in OnFailure= will be enqueued. See systemctl(1)'s --job-mode= option for details on the possible values. If this is set to "isolate", only a single unit may be listed in OnFailure=..

IgnoreOnIsolate=

Takes a boolean argument. If true, this unit will not be stopped when isolating another unit. Defaults to false for service, target, socket, busname, timer, and path units, and true for slice, scope, device, swap, mount, and automount units.

StopWhenUnneeded=

Takes a boolean argument. If true, this unit will be stopped when it is no longer used. Note that, in order to minimize the work to be executed, systemd will not stop units by default unless they are conflicting with other units, or the user explicitly requested their shut down. If this option is set, a unit will be automatically cleaned up if no other active unit requires it. Defaults to false.

RefuseManualStart=, RefuseManualStop=

Takes a boolean argument. If true, this unit can only be activated or deactivated indirectly. In this case, explicit start-up or termination requested by the user is denied, however if it is started or stopped as a dependency of another unit, start-up or termination will succeed. This is mostly a safety feature to ensure that the user does not accidentally activate units that are not intended to be activated explicitly, and not accidentally deactivate units that are not intended to be deactivated. These options default to false.

AllowIsolate=

Takes a boolean argument. If true, this unit may be used with the systemctl isolate command. Otherwise, this will be refused. It probably is a good idea to leave this disabled except for target units that shall be used similar to runlevels in SysV init systems, just as a precaution to avoid unusable system states. This option defaults to false.

DefaultDependencies=

Takes a boolean argument. If true, (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 completed 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 false. It is highly recommended to leave this option enabled for the majority of common units. If set to false, this option does not disable all implicit dependencies, just non-essential ones.

CollectMode=

Tweaks the "garbage collection" algorithm for this unit. Takes one of inactive or inactive-or-failed. If set to inactive the unit will be unloaded if it is in the inactive state and is not referenced by clients, jobs or other units --- however it is not unloaded if it is in the failed state. In failed mode, failed units are not unloaded until the user invoked systemctl reset-failed on them to reset the failed state, or an equivalent command. This behaviour is altered if this option is set to inactive-or-failed: in this case the unit is unloaded even if the unit is in a failed state, and thus an explicitly resetting of the failed state is not necessary. Note that if this mode is used unit results (such as exit codes, exit signals, consumed resources, ...) are flushed out immediately after the unit completed, except for what is stored in the logging subsystem. Defaults to inactive.

JobTimeoutSec=, JobRunningTimeoutSec=, JobTimeoutAction=, JobTimeoutRebootArgument=

When a job for this unit is queued, a time-out JobTimeoutSec= may be configured. Similarly, JobRunningTimeoutSec= starts counting when the queued job is actually started. If either time limit is reached, the job will be cancelled, the unit however will not change state or even enter the "failed" mode. This value defaults to "infinity" (job timeouts disabled), except for device units (JobRunningTimeoutSec= defaults to DefaultTimeoutStartSec=). NB: this timeout is independent from any unit-specific timeout (for example, the timeout set with TimeoutStartSec= in service units) as the job timeout has no effect on the unit itself, only on the job that might be pending for it. Or in other words: unit-specific timeouts are useful to abort unit state changes, and revert them. The job timeout set with this option however is useful to abort only the job waiting for the unit state to change.

JobTimeoutAction= optionally configures an additional action to take when the time-out is hit. It takes the same values as StartLimitAction=. Defaults to none. JobTimeoutRebootArgument= configures an optional reboot string to pass to the reboot(2) system call.

StartLimitIntervalSec=interval, StartLimitBurst=burst

Configure unit start rate limiting. Units which are started more than burst times within an interval time interval are not permitted to start any more. Use StartLimitIntervalSec= to configure the checking interval (defaults to DefaultStartLimitIntervalSec= in manager configuration file, set it to 0 to disable any kind of rate limiting). Use StartLimitBurst= to configure how many starts per interval are allowed (defaults to DefaultStartLimitBurst= in manager configuration file). These configuration options are particularly useful in conjunction with the service setting Restart= (see systemd.service(5)); however, they apply to all kinds of starts (including manual), not just those triggered by the Restart= logic. Note that units which are configured for Restart= and which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted manually at a later point, after the interval has passed. From this point on, the restart logic is activated again. Note that systemctl reset-failed will cause the restart rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit and the start limit interferes with that. Note that this rate-limiting is enforced after any unit condition checks are executed, and hence unit activations with failing conditions do not count towards this rate limit. This setting does not apply to slice, target, device, and scope units, since they are unit types whose activation may either never fail, or may succeed only a single time.

When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are flushed out too. This means that configuring start rate limiting for a unit that is not referenced continously has no effect.

StartLimitAction=

Configure the action to take if the rate limit configured with StartLimitIntervalSec= and StartLimitBurst= is hit. Takes one of none, reboot, reboot-force, reboot-immediate, poweroff, poweroff-force or poweroff-immediate. If none is set, hitting the rate limit will trigger no action besides that the start will not be permitted. reboot causes a reboot following the normal shutdown procedure (i.e. equivalent to systemctl reboot). reboot-force causes a forced reboot which will terminate all processes forcibly but should cause no dirty file systems on reboot (i.e. equivalent to systemctl reboot -f) and reboot-immediate causes immediate execution of the reboot(2) system call, which might result in data loss. Similarly, poweroff, poweroff-force, poweroff-immediate have the effect of powering down the system with similar semantics. Defaults to none.

FailureAction=, SuccessAction=

Configure the action to take when the unit stops and enters a failed state or inactive state. Takes the same values as the setting StartLimitAction= setting and executes the same actions (see systemd.unit(5)). Both options default to none.

RebootArgument=

Configure the optional argument for the reboot(2) system call if StartLimitAction= or FailureAction= is a reboot action. This works just like the optional argument to systemctl reboot command.

ConditionArchitecture=, ConditionVirtualization=, ConditionHost=, ConditionKernelCommandLine=, ConditionKernelVersion=, ConditionSecurity=, ConditionCapability=, ConditionACPower=, ConditionNeedsUpdate=, ConditionFirstBoot=, ConditionPathExists=, ConditionPathExistsGlob=, ConditionPathIsDirectory=, ConditionPathIsSymbolicLink=, ConditionPathIsMountPoint=, ConditionPathIsReadWrite=, ConditionDirectoryNotEmpty=, ConditionFileNotEmpty=, ConditionFileIsExecutable=, ConditionUser=, ConditionGroup=, ConditionControlGroupController=

Before starting a unit, verify that the specified condition is true. If it is not true, the starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still respected. A failing condition will not result in the unit being moved into a failure state. The condition is checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip units that do not apply to the local running system, for example because the kernel or runtime environment doesn't require its functionality. Use the various AssertArchitecture=, AssertVirtualization=, ... options for a similar mechanism that puts the unit in a failure state and logs about the failed check (see below).

ConditionArchitecture= may be used to check whether the system is running on a specific architecture. Takes one of x86, x86-64, ppc, ppc-le, ppc64, ppc64-le, ia64, parisc, parisc64, s390, s390x, sparc, sparc64, mips, mips-le, mips64, mips64-le, alpha, arm, arm-be, arm64, arm64-be, sh, sh64, m68k, tilegx, cris, arc, arc-be to test against a specific architecture. The architecture is determined from the information returned by uname(2) and is thus subject to personality(2). Note that a Personality= setting in the same unit file has no effect on this condition. A special architecture name native is mapped to the architecture the system manager itself is compiled for. The test may be negated by prepending an exclamation mark.

ConditionVirtualization= may be used to check whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation. Takes either boolean value to check if being executed in any virtualized environment, or one of vm and container to test against a generic type of virtualization solution, or one of qemu, kvm, zvm, vmware, microsoft, oracle, xen, bochs, uml, openvz, lxc, lxc-libvirt, systemd-nspawn, docker, rkt, wsl to test against a specific implementation, or private-users to check whether we are running in a user namespace. See systemd-detect-virt(1) for a full list of known virtualization technologies and their identifiers. If multiple virtualization technologies are nested, only the innermost is considered. The test may be negated by prepending an exclamation mark.

ConditionHost= may be used to match against the hostname or machine ID of the host. This either takes a hostname string (optionally with shell style globs) which is tested against the locally set hostname as returned by gethostname(2), or a machine ID formatted as string (see machine-id(5)). The test may be negated by prepending an exclamation mark.

ConditionKernelCommandLine= may be used to check whether a specific kernel command line option is set (or if prefixed with the exclamation mark unset). The argument must either be a single word, or an assignment (i.e. two words, separated "="). In the former case the kernel command line is searched for the word appearing as is, or as left hand side of an assignment. In the latter case, the exact assignment is looked for with right and left hand side matching.

ConditionKernelVersion= may be used to check whether the kernel version (as reported by uname -r) matches a certain expression (or if prefixed with the exclamation mark does not match it). The argument must be a single string. If the string starts with one of "<", "<=", "=", ">=", ">" a relative version comparison is done, otherwise the specified string is matched with shell-style globs.

Note that using the kernel version string is an unreliable way to determine which features are supported by a kernel, because of the widespread practice of backporting drivers, features, and fixes from newer upstream kernels into older versions provided by distributions. Hence, this check is inherently unportable and should not be used for units which may be used on different distributions.

ConditionSecurity= may be used to check whether the given security module is enabled on the system. Currently, the recognized values are selinux, apparmor, tomoyo, ima, smack and audit. The test may be negated by prepending an exclamation mark.

ConditionCapability= may be used to check whether the given capability exists in the capability bounding set of the service manager (i.e. this does not check whether capability is actually available in the permitted or effective sets, see capabilities(7) for details). Pass a capability name such as "CAP_MKNOD", possibly prefixed with an exclamation mark to negate the check.

ConditionACPower= may be used to check whether the system has AC power, or is exclusively battery powered at the time of activation of the unit. This takes a boolean argument. If set to true, the condition will hold only if at least one AC connector of the system is connected to a power source, or if no AC connectors are known. Conversely, if set to false, the condition will hold only if there is at least one AC connector known and all AC connectors are disconnected from a power source.

ConditionNeedsUpdate= takes one of /var or /etc as argument, possibly prefixed with a "!" (for inverting the condition). This condition may be used to conditionalize units on whether the specified directory requires an update because /usr's modification time is newer than the stamp file .updated in the specified directory. This is useful to implement offline updates of the vendor operating system resources in /usr that require updating of /etc or /var on the next following boot. Units making use of this condition should order themselves before systemd-update-done.service(8), to make sure they run before the stamp file's modification time gets reset indicating a completed update.

ConditionFirstBoot= takes a boolean argument. This condition may be used to conditionalize units on whether the system is booting up with an unpopulated /etc directory (specifically: an /etc with no /etc/machine-id). This may be used to populate /etc on the first boot after factory reset, or when a new system instance boots up for the first time.

With ConditionPathExists= a file existence condition is checked before a unit is started. If the specified absolute path name does not exist, the condition will fail. If the absolute path name passed to ConditionPathExists= is prefixed with an exclamation mark ("!"), the test is negated, and the unit is only started if the path does not exist.

ConditionPathExistsGlob= is similar to ConditionPathExists=, but checks for the existence of at least one file or directory matching the specified globbing pattern.

ConditionPathIsDirectory= is similar to ConditionPathExists= but verifies whether a certain path exists and is a directory.

ConditionPathIsSymbolicLink= is similar to ConditionPathExists= but verifies whether a certain path exists and is a symbolic link.

ConditionPathIsMountPoint= is similar to ConditionPathExists= but verifies whether a certain path exists and is a mount point.

ConditionPathIsReadWrite= is similar to ConditionPathExists= but verifies whether the underlying file system is readable and writable (i.e. not mounted read-only).

ConditionDirectoryNotEmpty= is similar to ConditionPathExists= but verifies whether a certain path exists and is a non-empty directory.

ConditionFileNotEmpty= is similar to ConditionPathExists= but verifies whether a certain path exists and refers to a regular file with a non-zero size.

ConditionFileIsExecutable= is similar to ConditionPathExists= but verifies whether a certain path exists, is a regular file and marked executable.

ConditionUser= takes a numeric "UID", a UNIX user name, or the special value "@system". This condition may be used to check whether the service manager is running as the given user. The special value "@system" can be used to check if the user id is within the system user range. This option is not useful for system services, as the system manager exclusively runs as the root user, and thus the test result is constant.

ConditionGroup= is similar to ConditionUser= but verifies that the service manager's real or effective group, or any of its auxiliary groups match the specified group or GID. This setting does not have a special value "@system".

ConditionControlGroupController= takes a cgroup controller name (eg. cpu), verifying that it is available for use on the system. For example, a particular controller may not be available if it was disabled on the kernel command line with "cgroup_disable="controller. Multiple controllers may be passed with a space separating them; in this case the condition will only pass if all listed controllers are available for use. Controllers unknown to systemd are ignored. Valid controllers are cpu, cpuacct, io, blkio, memory, devices, and pids.

If multiple conditions are specified, the unit will be executed if all of them apply (i.e. a logical AND is applied). Condition checks can be prefixed with a pipe symbol (|) in which case a condition becomes a triggering condition. If at least one triggering condition is defined for a unit, then the unit will be executed if at least one of the triggering conditions apply and all of the non-triggering conditions. If you prefix an argument with the pipe symbol and an exclamation mark, the pipe symbol must be passed first, the exclamation second. Except for ConditionPathIsSymbolicLink=, all path checks follow symlinks. If any of these options is assigned the empty string, the list of conditions is reset completely, all previous condition settings (of any kind) will have no effect.

AssertArchitecture=, AssertVirtualization=, AssertHost=, AssertKernelCommandLine=, AssertKernelVersion=, AssertSecurity=, AssertCapability=, AssertACPower=, AssertNeedsUpdate=, AssertFirstBoot=, AssertPathExists=, AssertPathExistsGlob=, AssertPathIsDirectory=, AssertPathIsSymbolicLink=, AssertPathIsMountPoint=, AssertPathIsReadWrite=, AssertDirectoryNotEmpty=, AssertFileNotEmpty=, AssertFileIsExecutable=, AssertUser=, AssertGroup=, AssertControlGroupController=

Similar to the ConditionArchitecture=, ConditionVirtualization=, ..., condition settings described above, these settings add assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting that is not met results in failure of the start job (which means this is logged loudly). Use assertion expressions for units that cannot operate when specific requirements are not met, and when this is something the administrator or user should look into.

SourcePath=

A path to a configuration file this unit has been generated from. This is primarily useful for implementation of generator tools that convert configuration from an external configuration file format into native unit files. This functionality should not be used in normal units.
 

MAPPING OF UNIT PROPERTIES TO THEIR INVERSES

Unit settings that create a relationship with a second unit usually show up in properties of both units, for example in systemctl show output. In some cases the name of the property is the same as the name of the configuration setting, but not always. This table lists the pairs of properties that are shown on two units which are connected through some dependency, and shows which property on "source" unit corresponds to which property on the "target" unit.


Table 3.  Forward and reverse unit properties

"Forward" property "Reverse" property Where used
Before= After= Both are unit file options
After= Before=
Requires= RequiredBy= A unit file option; an option in the [Install] section
Wants= WantedBy= A unit file option; an option in the [Install] section
PartOf= ConsistsOf= A unit file option; an automatic property
BindsTo= BoundBy= A unit file option; an automatic property
Requisite= RequisiteOf= A unit file option; an automatic property
Triggers= TriggeredBy= Automatic properties, see notes below
Conflicts= ConflictedBy= A unit file option; an automatic property
PropagatesReloadTo= ReloadPropagatedFrom= Both are unit file options
ReloadPropagatedFrom= PropagatesReloadTo=

Note: WantedBy= and RequiredBy= are used in the [Install] section to create symlinks in .wants/ and .requires/ directories. They cannot be used directly as a unit configuration setting.

Note: ConsistsOf=, BoundBy=, RequisiteOf=, ConflictedBy= are created implicitly along with their reverse and cannot be specified directly.

Note: Triggers= is created implicitly between a socket, path unit, or an automount unit, and the unit they activate. By default a unit with the same name is triggered, but this can be overriden using Sockets=, Service=, and Unit= settings. See systemd.service(5), systemd.socket(5), systemd.path(5), and systemd.automount(5) for details. TriggersBy= is created implicitly on the triggered unit.  

[INSTALL] SECTION OPTIONS

Unit files may include an "[Install]" section, which carries installation information for the unit. This section is not interpreted by systemd(1) during runtime; it is used by the enable and disable commands of the systemctl(1) tool during installation of a unit.

Alias=

A space-separated list of additional names this unit shall be installed under. The names listed here must have the same suffix (i.e. type) as the unit filename. This option may be specified more than once, in which case all listed names are used. At installation time, systemctl enable will create symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support aliasing.

WantedBy=, RequiredBy=

This option may be used more than once, or a space-separated list of unit names may be given. A symbolic link is created in the .wants/ or .requires/ directory of each of the listed units when this unit is installed by systemctl enable. This has the effect that a dependency of type Wants= or Requires= is added from the listed unit to the current unit. The primary result is that the current unit will be started when the listed unit is started. See the description of Wants= and Requires= in the [Unit] section for details.

WantedBy=foo.service in a service bar.service is mostly equivalent to Alias=foo.service.wants/bar.service in the same file. In case of template units, systemctl enable must be called with an instance name, and this instance will be added to the .wants/ or .requires/ list of the listed unit. E.g. WantedBy=getty.target in a service getty@.service will result in systemctl enable getty@tty2.service creating a getty.target.wants/getty@tty2.service link to getty@.service.

Also=

Additional units to install/deinstall when this unit is installed/deinstalled. If the user requests installation/deinstallation of a unit with this option configured, systemctl enable and systemctl disable will automatically install/uninstall units listed in this option as well.

This option may be used more than once, or a space-separated list of unit names may be given.

DefaultInstance=

In template unit files, this specifies for which instance the unit shall be enabled if the template is enabled without any explicitly set instance. This option has no effect in non-template unit files. The specified string must be usable as instance identifier.

The following specifiers are interpreted in the Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning see the next section.  

SPECIFIERS

Many settings resolve specifiers which may be used to write generic unit files referring to runtime or unit parameters that are replaced when the unit files are loaded. Specifiers must be known and resolvable for the setting to be valid. The following specifiers are understood:


Table 4. Specifiers available in unit files

Specifier Meaning Details
"%n" Full unit name  
"%N" Unescaped full unit name Same as "%n", but with escaping undone. This undoes the escaping used when generating unit names from arbitrary strings (see above).
"%p" Prefix name For instantiated units, this refers to the string before the "@" character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.
"%P" Unescaped prefix name Same as "%p", but with escaping undone
"%i" Instance name For instantiated units: this is the string between the "@" character and the suffix of the unit name.
"%I" Unescaped instance name Same as "%i", but with escaping undone
"%f" Unescaped filename This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the unescaped prefix name prepended with /. This implements unescaping according to the rules for escaping absolute file system paths discussed above.
"%t" Runtime directory root This is either /run (for the system manager) or the path "$XDG_RUNTIME_DIR" resolves to (for user managers).
"%S" State directory root This is either /var/lib (for the system manager) or the path "$XDG_CONFIG_HOME" resolves to (for user managers).
"%C" Cache directory root This is either /var/cache (for the system manager) or the path "$XDG_CACHE_HOME" resolves to (for user managers).
"%L" Log directory root This is either /var/log (for the system manager) or the path "$XDG_CONFIG_HOME" resolves to with /log appended (for user managers).
"%u" User name This is the name of the user running the service manager instance. In case of the system manager this resolves to "root".
"%U" User UID This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to "0".
"%h" User home directory This is the home directory of the user running the service manager instance. In case of the system manager this resolves to "/root".
"%s" User shell This is the shell of the user running the service manager instance. In case of the system manager this resolves to "/bin/sh".
"%m" Machine ID The machine ID of the running system, formatted as string. See machine-id(5) for more information.
"%b" Boot ID The boot ID of the running system, formatted as string. See random(4) for more information.
"%H" Host name The hostname of the running system at the point in time the unit configuration is loaded.
"%v" Kernel release Identical to uname -r output
"%%" Single percent sign Use "%%" in place of "%" to specify a single percent sign.

 

EXAMPLES

Example 1. Allowing units to be enabled

The following snippet (highlighted) allows a unit (e.g. foo.service) to be enabled via systemctl enable:

[Unit]
Description=Foo

[Service]
ExecStart=/usr/sbin/foo-daemon

[Install]
WantedBy=multi-user.target

After running systemctl enable, a symlink /etc/systemd/system/multi-user.target.wants/foo.service linking to the actual unit will be created. It tells systemd to pull in the unit when starting multi-user.target. The inverse systemctl disable will remove that symlink again.

Example 2. Overriding vendor settings

There are two methods of overriding vendor settings in unit files: copying the unit file from /lib/systemd/system to /etc/systemd/system and modifying the chosen settings. Alternatively, one can create a directory named unit.d/ within /etc/systemd/system and place a drop-in file name.conf there that only changes the specific settings one is interested in. Note that multiple such drop-in files are read if present, processed in lexicographic order of their filename.

The advantage of the first method is that one easily overrides the complete unit, the vendor unit is not parsed at all anymore. It has the disadvantage that improvements to the unit file by the vendor are not automatically incorporated on updates.

The advantage of the second method is that one only overrides the settings one specifically wants, where updates to the unit by the vendor automatically apply. This has the disadvantage that some future updates by the vendor might be incompatible with the local changes.

This also applies for user instances of systemd, but with different locations for the unit files. See the section on unit load paths for further details.

Suppose there is a vendor-supplied unit /lib/systemd/system/httpd.service with the following contents:

[Unit]
Description=Some HTTP server
After=remote-fs.target sqldb.service
Requires=sqldb.service
AssertPathExists=/srv/webserver

[Service]
Type=notify
ExecStart=/usr/sbin/some-fancy-httpd-server
Nice=5

[Install]
WantedBy=multi-user.target

Now one wants to change some settings as an administrator: firstly, in the local setup, /srv/webserver might not exist, because the HTTP server is configured to use /srv/www instead. Secondly, the local configuration makes the HTTP server also depend on a memory cache service, memcached.service, that should be pulled in (Requires=) and also be ordered appropriately (After=). Thirdly, in order to harden the service a bit more, the administrator would like to set the PrivateTmp= setting (see systemd.exec(5) for details). And lastly, the administrator would like to reset the niceness of the service to its default value of 0.

The first possibility is to copy the unit file to /etc/systemd/system/httpd.service and change the chosen settings:

[Unit]
Description=Some HTTP server
After=remote-fs.target sqldb.service memcached.service
Requires=sqldb.service memcached.service
AssertPathExists=/srv/www

[Service]
Type=notify
ExecStart=/usr/sbin/some-fancy-httpd-server
Nice=0
PrivateTmp=yes

[Install]
WantedBy=multi-user.target

Alternatively, the administrator could create a drop-in file /etc/systemd/system/httpd.service.d/local.conf with the following contents:

[Unit]
After=memcached.service
Requires=memcached.service
# Reset all assertions and then re-add the condition we want
AssertPathExists=
AssertPathExists=/srv/www

[Service]
Nice=0
PrivateTmp=yes

Note that for drop-in files, if one wants to remove entries from a setting that is parsed as a list (and is not a dependency), such as AssertPathExists= (or e.g. ExecStart= in service units), one needs to first clear the list before re-adding all entries except the one that is to be removed. Dependencies (After=, etc.) cannot be reset to an empty list, so dependencies can only be added in drop-ins. If you want to remove dependencies, you have to override the entire unit.  

SEE ALSO

systemd(1), systemctl(1), systemd.special(7), systemd.service(5), systemd.socket(5), systemd.device(5), systemd.mount(5), systemd.automount(5), systemd.swap(5), systemd.target(5), systemd.path(5), systemd.timer(5), systemd.scope(5), systemd.slice(5), systemd.time(7), systemd-analyze(1), capabilities(7), systemd.directives(7), uname(1)  

NOTES

1.
XDG Desktop Entry Specification
http://standards.freedesktop.org/desktop-entry-spec/latest/
2.
Interface Stability Promise
https://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise


 

Index

NAME
SYNOPSIS
DESCRIPTION
STRING ESCAPING FOR INCLUSION IN UNIT NAMES
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
UNIT FILE LOAD PATH
UNIT GARBAGE COLLECTION
[UNIT] SECTION OPTIONS
MAPPING OF UNIT PROPERTIES TO THEIR INVERSES
[INSTALL] SECTION OPTIONS
SPECIFIERS
EXAMPLES
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:54 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.RESOURCE-CONTROL

SYSTEMD.RESOURCE-CONTROL

Section: systemd.resource-control (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.resource-control - Resource control unit settings  

SYNOPSIS

slice.slice, scope.scope, service.service, socket.socket, mount.mount, swap.swap  

DESCRIPTION

Unit configuration files for services, slices, scopes, sockets, mount points, and swap devices share a subset of configuration options for resource control of spawned processes. Internally, this relies on the Linux Control Groups (cgroups) kernel concept for organizing processes in a hierarchical tree of named groups for the purpose of resource management.

This man page lists the configuration options shared by those six unit types. See systemd.unit(5) for the common options of all unit configuration files, and systemd.slice(5), systemd.scope(5), systemd.service(5), systemd.socket(5), systemd.mount(5), and systemd.swap(5) for more information on the specific unit configuration files. The resource control configuration options are configured in the [Slice], [Scope], [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type.

In addition, options which control resources available to programs executed by systemd are listed in systemd.exec(5). Those options complement options listed here.

See the m[blue]New Control Group Interfacesm[][1] for an introduction on how to make use of resource control APIs from programs.  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• Units with the Slice= setting set automatically acquire Requires= and After= dependencies on the specified slice unit.
 

UNIFIED AND LEGACY CONTROL GROUP HIERARCHIES

The unified control group hierarchy is the new version of kernel control group interface, see m[blue]cgroup-v2.txtm[][2]. Depending on the resource type, there are differences in resource control capabilities. Also, because of interface changes, some resource types have separate set of options on the unified hierarchy.

CPU

CPUWeight= and StartupCPUWeight= replace CPUShares= and StartupCPUShares=, respectively.

The "cpuacct" controller does not exist separately on the unified hierarchy.

Memory

MemoryMax= replaces MemoryLimit=. MemoryLow= and MemoryHigh= are effective only on unified hierarchy.

IO

IO prefixed settings are a superset of and replace BlockIO prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.

To ease the transition, there is best-effort translation between the two versions of settings. For each controller, if any of the settings for the unified hierarchy are present, all settings for the legacy hierarchy are ignored. If the resulting settings are for the other type of hierarchy, the configurations are translated before application.

Legacy control group hierarchy (see m[blue]cgroups.txtm[][3]), also called cgroup-v1, doesn't allow safe delegation of controllers to unprivileged processes. If the system uses the legacy control group hierarchy, resource control is disabled for systemd user instance, see systemd(1).  

OPTIONS

Units of the types listed above can have settings for resource control configuration:

CPUAccounting=

Turn on CPU usage accounting for this unit. Takes a boolean argument. Note that turning on CPU accounting for one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein. The system default for this setting may be controlled with DefaultCPUAccounting= in systemd-system.conf(5).

CPUWeight=weight, StartupCPUWeight=weight

Assign the specified CPU time weight to the processes executed, if the unified control group hierarchy is used on the system. These options take an integer value and control the "cpu.weight" control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2] and m[blue]sched-design-CFS.txtm[][4]. The available CPU time is split up among all units within one slice relative to their CPU time weight.

While StartupCPUWeight= only applies to the startup phase of the system, CPUWeight= applies to normal runtime of the system, and if the former is not set also to the startup phase. Using StartupCPUWeight= allows prioritizing specific services at boot-up differently than during normal runtime.

Implies "CPUAccounting=true".

These settings replace CPUShares= and StartupCPUShares=.

CPUQuota=

Assign the specified CPU time quota to the processes executed. Takes a percentage value, suffixed with "%". The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time available on one CPU. Use values > 100% for allotting CPU time on more than one CPU. This controls the "cpu.max" attribute on the unified control group hierarchy and "cpu.cfs_quota_us" on legacy. For details about these control group attributes, see m[blue]cgroup-v2.txtm[][2] and m[blue]sched-design-CFS.txtm[][4].

Example: CPUQuota=20% ensures that the executed processes will never get more than 20% CPU time on one CPU.

Implies "CPUAccounting=true".

MemoryAccounting=

Turn on process and kernel memory accounting for this unit. Takes a boolean argument. Note that turning on memory accounting for one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein. The system default for this setting may be controlled with DefaultMemoryAccounting= in systemd-system.conf(5).

MemoryLow=bytes

Specify the best-effort memory usage protection of the executed processes in this unit. If the memory usages of this unit and all its ancestors are below their low boundaries, this unit's memory won't be reclaimed as long as memory can be reclaimed from unprotected units.

Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. This controls the "memory.low" control group attribute. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2].

Implies "MemoryAccounting=true".

This setting is supported only if the unified control group hierarchy is used and disables MemoryLimit=.

MemoryHigh=bytes

Specify the high limit on memory usage of the executed processes in this unit. Memory usage may go above the limit if unavoidable, but the processes are heavily slowed down and memory is taken away aggressively in such cases. This is the main mechanism to control memory usage of a unit.

Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. If assigned the special value "infinity", no memory limit is applied. This controls the "memory.high" control group attribute. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2].

Implies "MemoryAccounting=true".

This setting is supported only if the unified control group hierarchy is used and disables MemoryLimit=.

MemoryMax=bytes

Specify the absolute limit on memory usage of the executed processes in this unit. If memory usage cannot be contained under the limit, out-of-memory killer is invoked inside the unit. It is recommended to use MemoryHigh= as the main control mechanism and use MemoryMax= as the last line of defense.

Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. If assigned the special value "infinity", no memory limit is applied. This controls the "memory.max" control group attribute. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2].

Implies "MemoryAccounting=true".

This setting replaces MemoryLimit=.

MemorySwapMax=bytes

Specify the absolute limit on swap usage of the executed processes in this unit.

Takes a swap size in bytes. If the value is suffixed with K, M, G or T, the specified swap size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the special value "infinity", no swap limit is applied. This controls the "memory.swap.max" control group attribute. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2].

Implies "MemoryAccounting=true".

This setting is supported only if the unified control group hierarchy is used and disables MemoryLimit=.

TasksAccounting=

Turn on task accounting for this unit. Takes a boolean argument. If enabled, the system manager will keep track of the number of tasks in the unit. The number of tasks accounted this way includes both kernel threads and userspace processes, with each thread counting individually. Note that turning on tasks accounting for one unit will also implicitly turn it on for all units contained in the same slice and for all its parent slices and the units contained therein. The system default for this setting may be controlled with DefaultTasksAccounting= in systemd-system.conf(5).

TasksMax=N

Specify the maximum number of tasks that may be created in the unit. This ensures that the number of tasks accounted for the unit (see above) stays below a specific limit. This either takes an absolute number of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the system. If assigned the special value "infinity", no tasks limit is applied. This controls the "pids.max" control group attribute. For details about this control group attribute, see m[blue]pids.txtm[][5].

Implies "TasksAccounting=true". The system default for this setting may be controlled with DefaultTasksMax= in systemd-system.conf(5).

IOAccounting=

Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly turn it on for all units contained in the same slice and all for its parent slices and the units contained therein. The system default for this setting may be controlled with DefaultIOAccounting= in systemd-system.conf(5).

This setting replaces BlockIOAccounting= and disables settings prefixed with BlockIO or StartupBlockIO.

IOWeight=weight, StartupIOWeight=weight

Set the default overall block I/O weight for the executed processes, if the unified control group hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block I/O weight. This controls the "io.weight" control group attribute, which defaults to 100. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2]. The available I/O bandwidth is split up among all units within one slice relative to their block I/O weight.

While StartupIOWeight= only applies to the startup phase of the system, IOWeight= applies to the later runtime of the system, and if the former is not set also to the startup phase. This allows prioritizing specific services at boot-up differently than during runtime.

Implies "IOAccounting=true".

These settings replace BlockIOWeight= and StartupBlockIOWeight= and disable settings prefixed with BlockIO or StartupBlockIO.

IODeviceWeight=device weight

Set the per-device overall block I/O weight for the executed processes, if the unified control group hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify the device specific weight value, between 1 and 10000. (Example: "/dev/sda 1000"). The file path may be specified as path to a block device node or as any other file, in which case the backing block device of the file system of the file is determined. This controls the "io.weight" control group attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2].

Implies "IOAccounting=true".

This setting replaces BlockIODeviceWeight= and disables settings prefixed with BlockIO or StartupBlockIO.

IOReadBandwidthMax=device bytes, IOWriteBandwidthMax=device bytes

Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified control group hierarchy is used on the system. This limit is not work-conserving and the executed processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of a file path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device node, or as any other file in which case the backing block device of the file system of the file is used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the "io.max" control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2].

Implies "IOAccounting=true".

These settings replace BlockIOReadBandwidth= and BlockIOWriteBandwidth= and disable settings prefixed with BlockIO or StartupBlockIO.

IOReadIOPSMax=device IOPS, IOWriteIOPSMax=device IOPS

Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the unified control group hierarchy is used on the system. This limit is not work-conserving and the executed processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of a file path and an IOPS value to specify the device specific IOPS. The file path may be a path to a block device node, or as any other file in which case the backing block device of the file system of the file is used. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS, GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example: "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the "io.max" control group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about this control group attribute, see m[blue]cgroup-v2.txtm[][2].

Implies "IOAccounting=true".

These settings are supported only if the unified control group hierarchy is used and disable settings prefixed with BlockIO or StartupBlockIO.

IPAccounting=

Takes a boolean argument. If true, turns on IPv4 and IPv6 network traffic accounting for packets sent or received by the unit. When this option is turned on, all IPv4 and IPv6 sockets created by any process of the unit are accounted for. When this option is used in socket units, it applies to all IPv4 and IPv6 sockets associated with it (including both listening and connection sockets where this applies). Note that for socket-activated services, this configuration setting and the accounting data of the service unit and the socket unit are kept separate, and displayed separately. No propagation of the setting and the collected statistics is done, in either direction. Moreover, any traffic sent or received on any of the socket unit's sockets is accounted to the socket unit --- and never to the service unit it might have activated, even if the socket is used by it. Note that IP accounting is currently not supported for slice units, and enabling this option for them has no effect. The system default for this setting may be controlled with DefaultIPAccounting= in systemd-system.conf(5).

IPAddressAllow=ADDRESS[/PREFIXLENGTH]..., IPAddressDeny=ADDRESS[/PREFIXLENGTH]...

Turn on address range network traffic filtering for packets sent and received over AF_INET and AF_INET6 sockets. Both directives take a space separated list of IPv4 or IPv6 addresses, each optionally suffixed with an address prefix length (separated by a "/" character). If the latter is omitted, the address is considered a host address, i.e. the prefix covers the whole address (32 for IPv4, 128 for IPv6).

The access lists configured with this option are applied to all sockets created by processes of this unit (or in the case of socket units, associated with it). The lists are implicitly combined with any lists configured for any of the parent slice units this unit might be a member of. By default all access lists are empty. When configured the lists are enforced as follows:

• Access will be granted in case its destination/source address matches any entry in the IPAddressAllow= setting.

• Otherwise, access will be denied in case its destination/source address matches any entry in the IPAddressDeny= setting.

• Otherwise, access will be granted.

In order to implement a whitelisting IP firewall, it is recommended to use a IPAddressDeny=any setting on an upper-level slice unit (such as the root slice -.slice or the slice containing all system services system.slice - see systemd.special(7) for details on these slice units), plus individual per-service IPAddressAllow= lines permitting network access to relevant services, and only them.

Note that for socket-activated services, the IP access list configured on the socket unit applies to all sockets associated with it directly, but not to any sockets created by the ultimately activated services for it. Conversely, the IP access list configured for the service is not applied to any sockets passed into the service via socket activation. Thus, it is usually a good idea, to replicate the IP access lists on both the socket and the service unit, however it often makes sense to maintain one list more open and the other one more restricted, depending on the usecase.

If these settings are used multiple times in the same unit the specified lists are combined. If an empty string is assigned to these settings the specific access list is reset and all previous settings undone.

In place of explicit IPv4 or IPv6 address and prefix length specifications a small set of symbolic names may be used. The following names are defined:


Table 1. Special address/network names

Symbolic Name Definition Meaning
any 0.0.0.0/0 ::/0 Any host
localhost 127.0.0.0/8 ::1/128 All addresses on the local loopback
link-local 169.254.0.0/16 fe80::/64 All link-local IP addresses
multicast 224.0.0.0/4 ff00::/8 All IP multicasting addresses

Note that these settings might not be supported on some systems (for example if eBPF control group support is not enabled in the underlying kernel or container manager). These settings will have no effect in that case. If compatibility with such systems is desired it is hence recommended to not exclusively rely on them for IP security.

DeviceAllow=

Control access to specific device nodes by the executed processes. Takes two space-separated strings: a device node specifier followed by a combination of r, w, m to control reading, writing, or creation of the specific device node(s) by the unit (mknod), respectively. This controls the "devices.allow" and "devices.deny" control group attributes. For details about these control group attributes, see m[blue]devices.txtm[][6].

The device node specifier is either a path to a device node in the file system, starting with /dev/, or a string starting with either "char-" or "block-" followed by a device group name, as listed in /proc/devices. The latter is useful to whitelist all current and future devices belonging to a specific device group at once. The device group is matched according to filename globbing rules, you may hence use the "*" and "?" wildcards. Examples: /dev/sda5 is a path to a device node, referring to an ATA or SCSI block device. "char-pts" and "char-alsa" are specifiers for all pseudo TTYs and all ALSA sound devices, respectively. "char-cpu/*" is a specifier matching all CPU related device groups.

DevicePolicy=auto|closed|strict

Control the policy for allowing device access:

strict

means to only allow types of access that are explicitly specified.

closed

in addition, allows access to standard pseudo devices including /dev/null, /dev/zero, /dev/full, /dev/random, and /dev/urandom.

auto

in addition, allows access to all devices if no explicit DeviceAllow= is present. This is the default.

Slice=

The name of the slice unit to place the unit in. Defaults to system.slice for all non-instantiated units of all unit types (except for slice units themselves see below). Instance units are by default placed in a subslice of system.slice that is named after the template name.

This option may be used to arrange systemd units in a hierarchy of slices each of which might have resource settings applied.

For units of type slice, the only accepted value for this setting is the parent slice. Since the name of a slice unit implies the parent slice, it is hence redundant to ever set this parameter directly for slice units.

Special care should be taken when relying on the default slice assignment in templated service units that have DefaultDependencies=no set, see systemd.service(5), section "Default Dependencies" for details.

Delegate=

Turns on delegation of further resource control partitioning to processes of the unit. Units where this is enabled may create and manage their own private subhierarchy of control groups below the control group of the unit itself. For unprivileged services (i.e. those using the User= setting) the unit's control group will be made accessible to the relevant user. When enabled the service manager will refrain from manipulating control groups or moving processes below the unit's control group, so that a clear concept of ownership is established: the control group tree above the unit's control group (i.e. towards the root control group) is owned and managed by the service manager of the host, while the control group tree below the unit's control group is owned and managed by the unit itself. Takes either a boolean argument or a list of control group controller names. If true, delegation is turned on, and all supported controllers are enabled for the unit, making them available to the unit's processes for management. If false, delegation is turned off entirely (and no additional controllers are enabled). If set to a list of controllers, delegation is turned on, and the specified controllers are enabled for the unit. Note that additional controllers than the ones specified might be made available as well, depending on configuration of the containing slice unit or other units contained in it. Note that assigning the empty string will enable delegation, but reset the list of controllers, all assignments prior to this will have no effect. Defaults to false.

Note that controller delegation to less privileged code is only safe on the unified control group hierarchy. Accordingly, access to the specified controllers will not be granted to unprivileged services on the legacy hierarchy, even when requested.

The following controller names may be specified: cpu, cpuacct, io, blkio, memory, devices, pids. Not all of these controllers are available on all kernels however, and some are specific to the unified hierarchy while others are specific to the legacy hierarchy. Also note that the kernel might support further controllers, which aren't covered here yet as delegation is either not supported at all for them or not defined cleanly.

 

DEPRECATED OPTIONS

The following options are deprecated. Use the indicated superseding options instead:

CPUShares=weight, StartupCPUShares=weight

Assign the specified CPU time share weight to the processes executed. These options take an integer value and control the "cpu.shares" control group attribute. The allowed range is 2 to 262144. Defaults to 1024. For details about this control group attribute, see m[blue]sched-design-CFS.txtm[][4]. The available CPU time is split up among all units within one slice relative to their CPU time share weight.

While StartupCPUShares= only applies to the startup phase of the system, CPUShares= applies to normal runtime of the system, and if the former is not set also to the startup phase. Using StartupCPUShares= allows prioritizing specific services at boot-up differently than during normal runtime.

Implies "CPUAccounting=true".

These settings are deprecated. Use CPUWeight= and StartupCPUWeight= instead.

MemoryLimit=bytes

Specify the limit on maximum memory usage of the executed processes. The limit specifies how much process and kernel memory can be used by tasks in this unit. Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is taken relative to the installed physical memory on the system. If assigned the special value "infinity", no memory limit is applied. This controls the "memory.limit_in_bytes" control group attribute. For details about this control group attribute, see m[blue]memory.txtm[][7].

Implies "MemoryAccounting=true".

This setting is deprecated. Use MemoryMax= instead.

BlockIOAccounting=

Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly turn it on for all units contained in the same slice and all for its parent slices and the units contained therein. The system default for this setting may be controlled with DefaultBlockIOAccounting= in systemd-system.conf(5).

This setting is deprecated. Use IOAccounting= instead.

BlockIOWeight=weight, StartupBlockIOWeight=weight

Set the default overall block I/O weight for the executed processes, if the legacy control group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default block I/O weight. This controls the "blkio.weight" control group attribute, which defaults to 500. For details about this control group attribute, see m[blue]blkio-controller.txtm[][8]. The available I/O bandwidth is split up among all units within one slice relative to their block I/O weight.

While StartupBlockIOWeight= only applies to the startup phase of the system, BlockIOWeight= applies to the later runtime of the system, and if the former is not set also to the startup phase. This allows prioritizing specific services at boot-up differently than during runtime.

Implies "BlockIOAccounting=true".

These settings are deprecated. Use IOWeight= and StartupIOWeight= instead.

BlockIODeviceWeight=device weight

Set the per-device overall block I/O weight for the executed processes, if the legacy control group hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be specified as path to a block device node or as any other file, in which case the backing block device of the file system of the file is determined. This controls the "blkio.weight_device" control group attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For details about this control group attribute, see m[blue]blkio-controller.txtm[][8].

Implies "BlockIOAccounting=true".

This setting is deprecated. Use IODeviceWeight= instead.

BlockIOReadBandwidth=device bytes, BlockIOWriteBandwidth=device bytes

Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device node, or as any other file in which case the backing block device of the file system of the file is used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the "blkio.throttle.read_bps_device" and "blkio.throttle.write_bps_device" control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details about these control group attributes, see m[blue]blkio-controller.txtm[][8].

Implies "BlockIOAccounting=true".

These settings are deprecated. Use IOReadBandwidthMax= and IOWriteBandwidthMax= instead.

 

SEE ALSO

systemd(1), systemd.unit(5), systemd.service(5), systemd.slice(5), systemd.scope(5), systemd.socket(5), systemd.mount(5), systemd.swap(5), systemd.exec(5), systemd.directives(7), systemd.special(7), The documentation for control groups and specific controllers in the Linux kernel: m[blue]cgroups.txtm[][3], m[blue]cpuacct.txtm[][9], m[blue]memory.txtm[][7], m[blue]blkio-controller.txtm[][8].  

NOTES

1.
New Control Group Interfaces
https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/
2.
cgroup-v2.txt
https://www.kernel.org/doc/Documentation/cgroup-v2.txt
3.
cgroups.txt
https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt
4.
sched-design-CFS.txt
https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt
5.
pids.txt
https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt
6.
devices.txt
https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt
7.
memory.txt
https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
8.
blkio-controller.txt
https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt
9.
cpuacct.txt
https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
UNIFIED AND LEGACY CONTROL GROUP HIERARCHIES
OPTIONS
DEPRECATED OPTIONS
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:54 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.PRESET

SYSTEMD.PRESET

Section: systemd.preset (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.preset - Service enablement presets  

SYNOPSIS

/etc/systemd/system-preset/*.preset

/run/systemd/system-preset/*.preset

/lib/systemd/system-preset/*.preset

/etc/systemd/user-preset/*.preset

/run/systemd/user-preset/*.preset

/usr/lib/systemd/user-preset/*.preset  

DESCRIPTION

Preset files may be used to encode policy which units shall be enabled by default and which ones shall be disabled. They are read by systemctl preset (for more information see systemctl(1)) which uses this information to enable or disable a unit according to preset policy. systemctl preset is used by the post install scriptlets of RPM packages (or other OS package formats), to enable/disable specific units by default on package installation, enforcing distribution, spin or administrator preset policy. This allows choosing a certain set of units to be enabled/disabled even before installing the actual package.

For more information on the preset logic please have a look at the m[blue]Presetsm[][1] document.

It is not recommended to ship preset files within the respective software packages implementing the units, but rather centralize them in a distribution or spin default policy, which can be amended by administrator policy.

If no preset files exist, systemctl preset will enable all units that are installed by default. If this is not desired and all units shall rather be disabled, it is necessary to ship a preset file with a single, catchall "disable *" line. (See example 1, below.)  

PRESET FILE FORMAT

The preset files contain a list of directives consisting of either the word "enable" or "disable" followed by a space and a unit name (possibly with shell style wildcards), separated by newlines. Empty lines and lines whose first non-whitespace character is # or ; are ignored.

Presets must refer to the "real" unit file, and not to any aliases. See systemd.unit(5) for a description of unit aliasing.

Two different directives are understood: "enable" may be used to enable units by default, "disable" to disable units by default.

If multiple lines apply to a unit name, the first matching one takes precedence over all others.

Each preset file shall be named in the style of <priority>-<policy-name>.preset. Files in /etc/ override files with the same name in /usr/lib/ and /run/. Files in /run/ override files with the same name in /lib/. Packages should install their preset files in /lib/. Files in /etc/ are reserved for the local administrator, who may use this logic to override the preset files installed by vendor packages. All preset files are sorted by their filename in lexicographic order, regardless of which of the directories they reside in. If multiple files specify the same unit name, the entry in the file with the lexicographically earliest name will be applied. It is recommended to prefix all filenames with a two-digit number and a dash, to simplify the ordering of the files.

If the administrator wants to disable a preset file supplied by the vendor, the recommended way is to place a symlink to /dev/null in /etc/systemd/system-preset/ bearing the same filename.  

EXAMPLES

Example 1. Default to off

# /lib/systemd/system-preset/99-default.preset

disable *

This disables all units. Due to the filename prefix "99-", it will be read last and hence can easily be overridden by spin or administrator preset policy.

Example 2. A GNOME spin

# /lib/systemd/system-preset/50-gnome.preset

enable gdm.service
enable colord.service
enable accounts-daemon.service
enable avahi-daemon.*

This enables the three mentioned units, plus all avahi-daemon regardless of which unit type. A file like this could be useful for inclusion in a GNOME spin of a distribution. It will ensure that the units necessary for GNOME are properly enabled as they are installed. It leaves all other units untouched, and subject to other (later) preset files, for example like the one from the first example above.

Example 3. Administrator policy

# /etc/systemd/system-preset/00-lennart.preset

enable httpd.service
enable sshd.service
enable postfix.service
disable *

This enables three specific services and disables all others. This is useful for administrators to specifically select the units to enable, and disable all others. Due to the filename prefix "00-" it will be read early and override all other preset policy files.  

SEE ALSO

systemd(1), systemctl(1), systemd-delta(1)  

NOTES

1.
Presets
https://www.freedesktop.org/wiki/Software/systemd/Preset


 

Index

NAME
SYNOPSIS
DESCRIPTION
PRESET FILE FORMAT
EXAMPLES
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:54 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.SLICE

SYSTEMD.SLICE

Section: systemd.slice (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.slice - Slice unit configuration  

SYNOPSIS

slice.slice  

DESCRIPTION

A unit configuration file whose name ends in ".slice" encodes information about a slice unit. A slice unit is a concept for hierarchically managing resources of a group of processes. This management is performed by creating a node in the Linux Control Group (cgroup) tree. Units that manage processes (primarily scope and service units) may be assigned to a specific slice. For each slice, certain resource limits may be set that apply to all processes of all units contained in that slice. Slices are organized hierarchically in a tree. The name of the slice encodes the location in the tree. The name consists of a dash-separated series of names, which describes the path to the slice from the root slice. The root slice is named -.slice. Example: foo-bar.slice is a slice that is located within foo.slice, which in turn is located in the root slice -.slice.

Note that slice units cannot be templated, nor is possible to add multiple names to a slice unit by creating additional symlinks to its unit file.

By default, service and scope units are placed in system.slice, virtual machines and containers registered with systemd-machined(1) are found in machine.slice, and user sessions handled by systemd-logind(1) in user.slice. See systemd.special(5) for more information.

See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The slice specific configuration options are configured in the [Slice] section. Currently, only generic resource control settings as described in systemd.resource-control(5) are allowed.

See the m[blue]New Control Group Interfacesm[][1] for an introduction on how to make use of slice units from programs.  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• Slice units automatically gain dependencies of type After= and Requires= on their immediate parent slice unit.
 

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Slice units will automatically have dependencies of type Conflicts= and Before= on shutdown.target. These ensure that slice units are removed prior to system shutdown. Only slice units involved with late system shutdown should disable DefaultDependencies= option.
 

SEE ALSO

systemd(1), systemd.unit(5), systemd.resource-control(5), systemd.service(5), systemd.scope(5), systemd.special(7), systemd.directives(7)  

NOTES

1.
New Control Group Interfaces
https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:54 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.PATH

SYSTEMD.PATH

Section: systemd.path (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.path - Path unit configuration  

SYNOPSIS

path.path  

DESCRIPTION

A unit configuration file whose name ends in ".path" encodes information about a path monitored by systemd, for path-based activation.

This man page lists the configuration options specific to this unit type. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The path specific configuration options are configured in the [Path] section.

For each path file, a matching unit file must exist, describing the unit to activate when the path changes. By default, a service by the same name as the path (except for the suffix) is activated. Example: a path file foo.path activates a matching service foo.service. The unit to activate may be controlled by Unit= (see below).

Internally, path units use the inotify(7) API to monitor file systems. Due to that, it suffers by the same limitations as inotify, and for example cannot be used to monitor files or directories changed by other machines on remote NFS file systems.  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• If a path unit is beneath another mount unit in the file system hierarchy, both a requirement and an ordering dependency between both units are created automatically.

• An implicit Before= dependency is added between a path unit and the unit it is supposed to activate.
 

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Path units will automatically have dependencies of type Before= on paths.target, dependencies of type After= and Requires= on sysinit.target, and 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 DefaultDependencies= option.

 

OPTIONS

Path files must include a [Path] section, which carries information about the path(s) it monitors. The options specific to the [Path] section of path units are the following:

PathExists=, PathExistsGlob=, PathChanged=, PathModified=, DirectoryNotEmpty=

Defines paths to monitor for certain changes: PathExists= may be used to watch the mere existence of a file or directory. If the file specified exists, the configured unit is activated. PathExistsGlob= works similar, but checks for the existence of at least one file matching the globbing pattern specified. PathChanged= may be used to watch a file or directory and activate the configured unit whenever it changes. It is not activated on every write to the watched file but it is activated if the file which was open for writing gets closed. PathModified= is similar, but additionally it is activated also on simple writes to the watched file. DirectoryNotEmpty= may be used to watch a directory and activate the configured unit whenever it contains at least one file.

The arguments of these directives must be absolute file system paths.

Multiple directives may be combined, of the same and of different types, to watch multiple paths. If the empty string is assigned to any of these options, the list of paths to watch is reset, and any prior assignments of these options will not have any effect.

If a path already exists (in case of PathExists= and PathExistsGlob=) or a directory already is not empty (in case of DirectoryNotEmpty=) at the time the path unit is activated, then the configured unit is immediately activated as well. Something similar does not apply to PathChanged= and PathModified=.

If the path itself or any of the containing directories are not accessible, systemd will watch for permission changes and notice that conditions are satisfied when permissions allow that.

Unit=

The unit to activate when any of the configured paths changes. The argument is a unit name, whose suffix is not ".path". If not specified, this value defaults to a service that has the same name as the path unit, except for the suffix. (See above.) It is recommended that the unit name that is activated and the unit name of the path unit are named identical, except for the suffix.

MakeDirectory=

Takes a boolean argument. If true, the directories to watch are created before watching. This option is ignored for PathExists= settings. Defaults to false.

DirectoryMode=

If MakeDirectory= is enabled, use the mode specified here to create the directories in question. Takes an access mode in octal notation. Defaults to 0755.
 

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), systemd.service(5), inotify(7), systemd.directives(7)


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
OPTIONS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:54 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.NETDEV

SYSTEMD.NETDEV

Section: systemd.network (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.netdev - Virtual Network Device configuration  

SYNOPSIS

netdev.netdev  

DESCRIPTION

Network setup is performed by systemd-networkd(8).

The main Virtual Network Device file must have the extension .netdev; other extensions are ignored. Virtual network devices are created as soon as networkd is started. If a netdev with the specified name already exists, networkd will use that as-is rather than create its own. Note that the settings of the pre-existing netdev will not be changed by networkd.

The .netdev files are read from the files located in the system network directory /lib/systemd/network, the volatile runtime network directory /run/systemd/network and the local administration network directory /etc/systemd/network. All configuration files are collectively sorted and processed in lexical order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in /etc have the highest priority, files in /run take precedence over files with the same name in /lib. This can be used to override a system-supplied configuration file with a local file if needed. As a special case, an empty file (file size 0) or symlink with the same name pointing to /dev/null disables the configuration file entirely (it is "masked").

Along with the netdev file foo.netdev, a "drop-in" directory foo.netdev.d/ may exist. All files with the suffix ".conf" from this directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers.

In addition to /etc/systemd/network, drop-in ".d" directories can be placed in /lib/systemd/network or /run/systemd/network directories. Drop-in files in /etc take precedence over those in /run which in turn take precedence over those in /lib. Drop-in files under any of these directories take precedence over the main netdev file wherever located. (Of course, since /run is temporary and /usr/lib is for vendors, it is unlikely drop-ins should be used in either of those places.)  

SUPPORTED NETDEV KINDS

The following kinds of virtual network devices may be configured in .netdev files:


Table 1. Supported kinds of virtual network devices

Kind Description
bond A bond device is an aggregation of all its slave devices. See m[blue]Linux Ethernet Bonding Driver HOWTOm[][1] for details.Local configuration
bridge A bridge device is a software switch, and each of its slave devices and the bridge itself are ports of the switch.
dummy A dummy device drops all packets sent to it.
gre A Level 3 GRE tunnel over IPv4. See m[blue]RFC 2784m[][2] for details.
gretap A Level 2 GRE tunnel over IPv4.
ip6gre A Level 3 GRE tunnel over IPv6.
ip6tnl An IPv4 or IPv6 tunnel over IPv6
ip6gretap A Level 2 GRE tunnel over IPv6.
ipip An IPv4 over IPv4 tunnel.
ipvlan An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering.
macvlan A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.
macvtap A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering.
sit An IPv6 over IPv4 tunnel.
tap A persistent Level 2 tunnel between a network device and a device node.
tun A persistent Level 3 tunnel between a network device and a device node.
veth An Ethernet tunnel between a pair of network devices.
vlan A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See m[blue]IEEE 802.1Qm[][3] for details.
vti An IPv4 over IPSec tunnel.
vti6 An IPv6 over IPSec tunnel.
vxlan A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.
geneve A GEneric NEtwork Virtualization Encapsulation (GENEVE) netdev driver.
vrf A Virtual Routing and Forwarding (m[blue]VRFm[][4]) interface to create separate routing and forwarding domains.
vcan The virtual CAN driver (vcan). Similar to the network loopback devices, vcan offers a virtual local CAN interface.
vxcan The virtual CAN tunnel driver (vxcan). Similar to the virtual ethernet driver veth, vxcan implements a local CAN traffic tunnel between two virtual CAN network devices. When creating a vxcan, two vxcan devices are created as pair. When one end receives the packet it appears on its pair and vice versa. The vxcan can be used for cross namespace communication.
wireguard WireGuard Secure Network Tunnel.

 

[MATCH] SECTION OPTIONS

A virtual network device is only created if the "[Match]" section matches the current environment, or if the section is empty. The following keys are accepted:

Host=

Matches against the hostname or machine ID of the host. See "ConditionHost=" in systemd.unit(5) for details.

Virtualization=

Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation. See "ConditionVirtualization=" in systemd.unit(5) for details.

KernelCommandLine=

Checks whether a specific kernel command line option is set (or if prefixed with the exclamation mark unset). See "ConditionKernelCommandLine=" in systemd.unit(5) for details.

KernelVersion=

Checks whether the kernel version (as reported by uname -r) matches a certain expression (or if prefixed with the exclamation mark does not match it). See "ConditionKernelVersion=" in systemd.unit(5) for details.

Architecture=

Checks whether the system is running on a specific architecture. See "ConditionArchitecture=" in systemd.unit(5) for details.
 

[NETDEV] SECTION OPTIONS

The "[NetDev]" section accepts the following keys:

Description=

A free-form description of the netdev.

Name=

The interface name used when creating the netdev. This option is compulsory.

Kind=

The netdev kind. This option is compulsory. See the "Supported netdev kinds" section for the valid keys.

MTUBytes=

The maximum transmission unit in bytes to set for the device. The usual suffixes K, M, G, are supported and are understood to the base of 1024. This key is not currently supported for "tun" or "tap" devices.

MACAddress=

The MAC address to use for the device. If none is given, one is generated based on the interface name and the machine-id(5). This key is not currently supported for "tun" or "tap" devices.
 

[BRIDGE] SECTION OPTIONS

The "[Bridge]" section only applies for netdevs of kind "bridge", and accepts the following keys:

HelloTimeSec=

HelloTimeSec specifies the number of seconds between two hello packets sent out by the root bridge and the designated bridges. Hello packets are used to communicate information about the topology throughout the entire bridged local area network.

MaxAgeSec=

MaxAgeSec specifies the number of seconds of maximum message age. If the last seen (received) hello packet is more than this number of seconds old, the bridge in question will start the takeover procedure in attempt to become the Root Bridge itself.

ForwardDelaySec=

ForwardDelaySec specifies the number of seconds spent in each of the Listening and Learning states before the Forwarding state is entered.

AgeingTimeSec=

This specifies the number of seconds a MAC Address will be kept in the forwarding database after having a packet received from this MAC Address.

Priority=

The priority of the bridge. An integer between 0 and 65535. A lower value means higher priority. The bridge having the lowest priority will be elected as root bridge.

GroupForwardMask=

A 16-bit bitmask represented as an integer which allows forwarding of link local frames with 802.1D reserved addresses (01:80:C2:00:00:0X). A logical AND is performed between the specified bitmask and the exponentiation of 2^X, the lower nibble of the last octet of the MAC address. For example, a value of 8 would allow forwarding of frames addressed to 01:80:C2:00:00:03 (802.1X PAE).

DefaultPVID=

This specifies the default port VLAN ID of a newly attached bridge port. Set this to an integer in the range 1-4094 or "none" to disable the PVID.

MulticastQuerier=

A boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. If enabled, the kernel will send general ICMP queries from a zero source address. This feature should allow faster convergence on startup, but it causes some multicast-aware switches to misbehave and disrupt forwarding of multicast packets. When unset, the kernel's default setting applies.

MulticastSnooping=

A boolean. This setting controls the IFLA_BR_MCAST_SNOOPING option in the kernel. If enabled, IGMP snooping monitors the Internet Group Management Protocol (IGMP) traffic between hosts and multicast routers. When unset, the kernel's default setting applies.

VLANFiltering=

A boolean. This setting controls the IFLA_BR_VLAN_FILTERING option in the kernel. If enabled, the bridge will be started in VLAN-filtering mode. When unset, the kernel's default setting applies.

STP=

A boolean. This enables the bridge's Spanning Tree Protocol (STP). When unset, the kernel's default setting applies.
 

[VLAN] SECTION OPTIONS

The "[VLAN]" section only applies for netdevs of kind "vlan", and accepts the following key:

Id=

The VLAN ID to use. An integer in the range 0-4094. This option is compulsory.

GVRP=

The Generic VLAN Registration Protocol (GVRP) is a protocol that allows automatic learning of VLANs on a network. A boolean. When unset, the kernel's default setting applies.

MVRP=

Multiple VLAN Registration Protocol (MVRP) formerly known as GARP VLAN Registration Protocol (GVRP) is a standards-based Layer 2 network protocol, for automatic configuration of VLAN information on switches. It was defined in the 802.1ak amendment to 802.1Q-2005. A boolean. When unset, the kernel's default setting applies.

LooseBinding=

The VLAN loose binding mode, in which only the operational state is passed from the parent to the associated VLANs, but the VLAN device state is not changed. A boolean. When unset, the kernel's default setting applies.

ReorderHeader=

The VLAN reorder header is set VLAN interfaces behave like physical interfaces. A boolean. When unset, the kernel's default setting applies.
 

[MACVLAN] SECTION OPTIONS

The "[MACVLAN]" section only applies for netdevs of kind "macvlan", and accepts the following key:

Mode=

The MACVLAN mode to use. The supported options are "private", "vepa", "bridge", and "passthru".
 

[MACVTAP] SECTION OPTIONS

The "[MACVTAP]" section applies for netdevs of kind "macvtap" and accepts the same key as "[MACVLAN]".  

[IPVLAN] SECTION OPTIONS

The "[IPVLAN]" section only applies for netdevs of kind "ipvlan", and accepts the following key:

Mode=

The IPVLAN mode to use. The supported options are "L2","L3" and "L3S".

Flags=

The IPVLAN flags to use. The supported options are "bridge","private" and "vepa".
 

[VXLAN] SECTION OPTIONS

The "[VXLAN]" section only applies for netdevs of kind "vxlan", and accepts the following keys:

Id=

The VXLAN ID to use.

Remote=

Configures destination multicast group IP address.

Local=

Configures local IP address.

TOS=

The Type Of Service byte value for a vxlan interface.

TTL=

A fixed Time To Live N on Virtual eXtensible Local Area Network packets. N is a number in the range 1-255. 0 is a special value meaning that packets inherit the TTL value.

MacLearning=

A boolean. When true, enables dynamic MAC learning to discover remote MAC addresses.

FDBAgeingSec=

The lifetime of Forwarding Database entry learnt by the kernel, in seconds.

MaximumFDBEntries=

Configures maximum number of FDB entries.

ReduceARPProxy=

A boolean. When true, bridge-connected VXLAN tunnel endpoint answers ARP requests from the local bridge on behalf of remote Distributed Overlay Virtual Ethernet m[blue](DVOE)m[][5] clients. Defaults to false.

L2MissNotification=

A boolean. When true, enables netlink LLADDR miss notifications.

L3MissNotification=

A boolean. When true, enables netlink IP address miss notifications.

RouteShortCircuit=

A boolean. When true, route short circuiting is turned on.

UDPChecksum=

A boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on.

UDP6ZeroChecksumTx=

A boolean. When true, sending zero checksums in VXLAN/IPv6 is turned on.

UDP6ZeroChecksumRx=

A boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on.

RemoteChecksumTx=

A boolean. When true, remote transmit checksum offload of VXLAN is turned on.

RemoteChecksumRx=

A boolean. When true, remote receive checksum offload in VXLAN is turned on.

GroupPolicyExtension=

A boolean. When true, it enables Group Policy VXLAN extension security label mechanism across network peers based on VXLAN. For details about the Group Policy VXLAN, see the m[blue]VXLAN Group Policym[][6] document. Defaults to false.

DestinationPort=

Configures the default destination UDP port on a per-device basis. If destination port is not specified then Linux kernel default will be used. Set destination port 4789 to get the IANA assigned value. If not set or if the destination port is assigned the empty string the default port of 4789 is used.

PortRange=

Configures VXLAN port range. VXLAN bases source UDP port based on flow to help the receiver to be able to load balance based on outer header flow. It restricts the port range to the normal UDP local ports, and allows overriding via configuration.

FlowLabel=

Specifies the flow label to use in outgoing packets. The valid range is 0-1048575.
 

[GENEVE] SECTION OPTIONS

The "[GENEVE]" section only applies for netdevs of kind "geneve", and accepts the following keys:

Id=

Specifies the Virtual Network Identifier (VNI) to use. Ranges [0-16777215].

Remote=

Specifies the unicast destination IP address to use in outgoing packets.

TOS=

Specifies the TOS value to use in outgoing packets. Ranges [1-255].

TTL=

Specifies the TTL value to use in outgoing packets. Ranges [1-255].

UDPChecksum=

A boolean. When true, specifies if UDP checksum is calculated for transmitted packets over IPv4.

UDP6ZeroChecksumTx=

A boolean. When true, skip UDP checksum calculation for transmitted packets over IPv6.

UDP6ZeroChecksumRx=

A boolean. When true, allows incoming UDP packets over IPv6 with zero checksum field.

DestinationPort=

Specifies destination port. Defaults to 6081. If not set or assigned the empty string, the default port of 6081 is used.

FlowLabel=

Specifies the flow label to use in outgoing packets.
 

[TUNNEL] SECTION OPTIONS

The "[Tunnel]" section only applies for netdevs of kind "ipip", "sit", "gre", "gretap", "ip6gre", "ip6gretap", "vti", "vti6", and "ip6tnl" and accepts the following keys:

Local=

A static local address for tunneled packets. It must be an address on another interface of this host.

Remote=

The remote endpoint of the tunnel.

TOS=

The Type Of Service byte value for a tunnel interface. For details about the TOS, see the m[blue]Type of Service in the Internet Protocol Suitem[][7] document.

TTL=

A fixed Time To Live N on tunneled packets. N is a number in the range 1-255. 0 is a special value meaning that packets inherit the TTL value. The default value for IPv4 tunnels is: inherit. The default value for IPv6 tunnels is 64.

DiscoverPathMTU=

A boolean. When true, enables Path MTU Discovery on the tunnel.

IPv6FlowLabel=

Configures the 20-bit flow label (see m[blue]RFC 6437m[][8]) field in the IPv6 header (see m[blue]RFC 2460m[][9]), which is used by a node to label packets of a flow. It is only used for IPv6 tunnels. A flow label of zero is used to indicate packets that have not been labeled. It can be configured to a value in the range 0-0xFFFFF, or be set to "inherit", in which case the original flowlabel is used.

CopyDSCP=

A boolean. When true, the Differentiated Service Code Point (DSCP) field will be copied to the inner header from outer header during the decapsulation of an IPv6 tunnel packet. DSCP is a field in an IP packet that enables different levels of service to be assigned to network traffic. Defaults to "no".

EncapsulationLimit=

The Tunnel Encapsulation Limit option specifies how many additional levels of encapsulation are permitted to be prepended to the packet. For example, a Tunnel Encapsulation Limit option containing a limit value of zero means that a packet carrying that option may not enter another tunnel before exiting the current tunnel. (see m[blue]RFC 2473m[][10]). The valid range is 0-255 and "none". Defaults to 4.

Key=

The Key= parameter specifies the same key to use in both directions (InputKey= and OutputKey=). The Key= is either a number or an IPv4 address-like dotted quad. It is used as mark-configured SAD/SPD entry as part of the lookup key (both in data and control path) in ip xfrm (framework used to implement IPsec protocol). See m[blue]ip-xfrm --- transform configurationm[][11] for details. It is only used for VTI/VTI6 tunnels.

InputKey=

The InputKey= parameter specifies the key to use for input. The format is same as Key=. It is only used for VTI/VTI6 tunnels.

OutputKey=

The OutputKey= parameter specifies the key to use for output. The format is same as Key=. It is only used for VTI/VTI6 tunnels.

Mode=

An "ip6tnl" tunnel can be in one of three modes "ip6ip6" for IPv6 over IPv6, "ipip6" for IPv4 over IPv6 or "any" for either.

Independent=

A boolean. When true tunnel does not require .network file. Created as "tunnel@NONE". Defaults to "false".

AllowLocalRemote=

A boolean. When true allows tunnel traffic on ip6tnl devices where the remote endpoint is a local host address. Defaults to unset.
 

[PEER] SECTION OPTIONS

The "[Peer]" section only applies for netdevs of kind "veth" and accepts the following keys:

Name=

The interface name used when creating the netdev. This option is compulsory.

MACAddress=

The peer MACAddress, if not set, it is generated in the same way as the MAC address of the main interface.
 

[VXCAN] SECTION OPTIONS

The "[VXCAN]" section only applies for netdevs of kind "vxcan" and accepts the following key:

Peer=

The peer interface name used when creating the netdev. This option is compulsory.
 

[TUN] SECTION OPTIONS

The "[Tun]" section only applies for netdevs of kind "tun", and accepts the following keys:

OneQueue=

Takes a boolean argument. Configures whether all packets are queued at the device (enabled), or a fixed number of packets are queued at the device and the rest at the "qdisc". Defaults to "no".

MultiQueue=

Takes a boolean argument. Configures whether to use multiple file descriptors (queues) to parallelize packets sending and receiving. Defaults to "no".

PacketInfo=

Takes a boolean argument. Configures whether packets should be prepended with four extra bytes (two flag bytes and two protocol bytes). If disabled, it indicates that the packets will be pure IP packets. Defaults to "no".

VNetHeader=

Takes a boolean argument. Configures IFF_VNET_HDR flag for a tap device. It allows sending and receiving larger Generic Segmentation Offload (GSO) packets. This may increase throughput significantly. Defaults to "no".

User=

User to grant access to the /dev/net/tun device.

Group=

Group to grant access to the /dev/net/tun device.
 

[TAP] SECTION OPTIONS

The "[Tap]" section only applies for netdevs of kind "tap", and accepts the same keys as the "[Tun]" section.  

[WIREGUARD] SECTION OPTIONS

The "[WireGuard]" section accepts the following keys:

PrivateKey=

The Base64 encoded private key for the interface. It can be generated using the wg genkey command (see wg(8)). This option is mandatory to use wireguard.

ListenPort=

Sets UDP port for listening. Takes either value between 1 and 65535 or "auto". If "auto" is specified, the port is automatically generated based on interface name. Defaults to "auto".

FwMark=

Sets a firewall mark on outgoing wireguard packets from this interface.
 

[WIREGUARDPEER] SECTION OPTIONS

The "[WireGuardPeer]" section accepts the following keys:

PublicKey=

Sets a Base64 encoded public key calculated by wg pubkey (see wg(8)) from a private key, and usually transmitted out of band to the author of the configuration file. This option is mandatory for this section.

PresharedKey=

Optional preshared key for the interface. It can be generated by the wg genpsk command. This option adds an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance.

AllowedIPs=

Sets a comma-separated list of IP (v4 or v6) addresses with CIDR masks from which this peer is allowed to send incoming traffic and to which outgoing traffic for this peer is directed. The catch-all 0.0.0.0/0 may be specified for matching all IPv4 addresses, and ::/0 may be specified for matching all IPv6 addresses.

Endpoint=

Sets an endpoint IP address or hostname, followed by a colon, and then a port number. This endpoint will be updated automatically once to the most recent source IP address and port of correctly authenticated packets from the peer at configuration time.

PersistentKeepalive=

Sets a seconds interval, between 1 and 65535 inclusive, of how often to send an authenticated empty packet to the peer for the purpose of keeping a stateful firewall or NAT mapping valid persistently. For example, if the interface very rarely sends traffic, but it might at anytime receive traffic from a peer, and it is behind NAT, the interface might benefit from having a persistent keepalive interval of 25 seconds. If set to 0 or "off", this option is disabled. By default or when unspecified, this option is off. Most users will not need this.
 

[BOND] SECTION OPTIONS

The "[Bond]" section accepts the following key:

Mode=

Specifies one of the bonding policies. The default is "balance-rr" (round robin). Possible values are "balance-rr", "active-backup", "balance-xor", "broadcast", "802.3ad", "balance-tlb", and "balance-alb".

TransmitHashPolicy=

Selects the transmit hash policy to use for slave selection in balance-xor, 802.3ad, and tlb modes. Possible values are "layer2", "layer3+4", "layer2+3", "encap2+3", and "encap3+4".

LACPTransmitRate=

Specifies the rate with which link partner transmits Link Aggregation Control Protocol Data Unit packets in 802.3ad mode. Possible values are "slow", which requests partner to transmit LACPDUs every 30 seconds, and "fast", which requests partner to transmit LACPDUs every second. The default value is "slow".

MIIMonitorSec=

Specifies the frequency that Media Independent Interface link monitoring will occur. A value of zero disables MII link monitoring. This value is rounded down to the nearest millisecond. The default value is 0.

UpDelaySec=

Specifies the delay before a link is enabled after a link up status has been detected. This value is rounded down to a multiple of MIIMonitorSec. The default value is 0.

DownDelaySec=

Specifies the delay before a link is disabled after a link down status has been detected. This value is rounded down to a multiple of MIIMonitorSec. The default value is 0.

LearnPacketIntervalSec=

Specifies the number of seconds between instances where the bonding driver sends learning packets to each slave peer switch. The valid range is 1-0x7fffffff; the default value is 1. This option has an effect only for the balance-tlb and balance-alb modes.

AdSelect=

Specifies the 802.3ad aggregation selection logic to use. Possible values are "stable", "bandwidth" and "count".

FailOverMACPolicy=

Specifies whether the active-backup mode should set all slaves to the same MAC address at the time of enslavement or, when enabled, to perform special handling of the bond's MAC address in accordance with the selected policy. The default policy is none. Possible values are "none", "active" and "follow".

ARPValidate=

Specifies whether or not ARP probes and replies should be validated in any mode that supports ARP monitoring, or whether non-ARP traffic should be filtered (disregarded) for link monitoring purposes. Possible values are "none", "active", "backup" and "all".

ARPIntervalSec=

Specifies the ARP link monitoring frequency in milliseconds. A value of 0 disables ARP monitoring. The default value is 0.

ARPIPTargets=

Specifies the IP addresses to use as ARP monitoring peers when ARPIntervalSec is greater than 0. These are the targets of the ARP request sent to determine the health of the link to the targets. Specify these values in IPv4 dotted decimal format. At least one IP address must be given for ARP monitoring to function. The maximum number of targets that can be specified is 16. The default value is no IP addresses.

ARPAllTargets=

Specifies the quantity of ARPIPTargets that must be reachable in order for the ARP monitor to consider a slave as being up. This option affects only active-backup mode for slaves with ARPValidate enabled. Possible values are "any" and "all".

PrimaryReselectPolicy=

Specifies the reselection policy for the primary slave. This affects how the primary slave is chosen to become the active slave when failure of the active slave or recovery of the primary slave occurs. This option is designed to prevent flip-flopping between the primary slave and other slaves. Possible values are "always", "better" and "failure".

ResendIGMP=

Specifies the number of IGMP membership reports to be issued after a failover event. One membership report is issued immediately after the failover, subsequent packets are sent in each 200ms interval. The valid range is 0-255. Defaults to 1. A value of 0 prevents the IGMP membership report from being issued in response to the failover event.

PacketsPerSlave=

Specify the number of packets to transmit through a slave before moving to the next one. When set to 0, then a slave is chosen at random. The valid range is 0-65535. Defaults to 1. This option only has effect when in balance-rr mode.

GratuitousARP=

Specify the number of peer notifications (gratuitous ARPs and unsolicited IPv6 Neighbor Advertisements) to be issued after a failover event. As soon as the link is up on the new slave, a peer notification is sent on the bonding device and each VLAN sub-device. This is repeated at each link monitor interval (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is greater than 1. The valid range is 0-255. The default value is 1. These options affect only the active-backup mode.

AllSlavesActive=

A boolean. Specifies that duplicate frames (received on inactive ports) should be dropped when false, or delivered when true. Normally, bonding will drop duplicate frames (received on inactive ports), which is desirable for most users. But there are some times it is nice to allow duplicate frames to be delivered. The default value is false (drop duplicate frames received on inactive ports).

MinLinks=

Specifies the minimum number of links that must be active before asserting carrier. The default value is 0.

For more detail information see m[blue]Linux Ethernet Bonding Driver HOWTOm[][1]  

EXAMPLE

Example 1. /etc/systemd/network/25-bridge.netdev

[NetDev]
Name=bridge0
Kind=bridge

Example 2. /etc/systemd/network/25-vlan1.netdev

[Match]
Virtualization=no

[NetDev]
Name=vlan1
Kind=vlan

[VLAN]
Id=1

Example 3. /etc/systemd/network/25-ipip.netdev

[NetDev]
Name=ipip-tun
Kind=ipip
MTUBytes=1480

[Tunnel]
Local=192.168.223.238
Remote=192.169.224.239
TTL=64

Example 4. /etc/systemd/network/25-tap.netdev

[NetDev]
Name=tap-test
Kind=tap

[Tap]
MultiQueue=true
PacketInfo=true

Example 5. /etc/systemd/network/25-sit.netdev

[NetDev]
Name=sit-tun
Kind=sit
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239

Example 6. /etc/systemd/network/25-gre.netdev

[NetDev]
Name=gre-tun
Kind=gre
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239

Example 7. /etc/systemd/network/25-vti.netdev

[NetDev]
Name=vti-tun
Kind=vti
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239

Example 8. /etc/systemd/network/25-veth.netdev

[NetDev]
Name=veth-test
Kind=veth

[Peer]
Name=veth-peer

Example 9. /etc/systemd/network/25-bond.netdev

[NetDev]
Name=bond1
Kind=bond

[Bond]
Mode=802.3ad
TransmitHashPolicy=layer3+4
MIIMonitorSec=1s
LACPTransmitRate=fast

Example 10. /etc/systemd/network/25-dummy.netdev

[NetDev]
Name=dummy-test
Kind=dummy
MACAddress=12:34:56:78:9a:bc

Example 11. /etc/systemd/network/25-vrf.netdev

Create a VRF interface with table 42.

[NetDev]
Name=vrf-test
Kind=vrf

[VRF]
Table=42

Example 12. /etc/systemd/network/25-macvtap.netdev

Create a MacVTap device.

[NetDev]
Name=macvtap-test
Kind=macvtap
      

Example 13. /etc/systemd/network/25-wireguard.netdev

[NetDev]
Name=wg0
Kind=wireguard

[WireGuard]
PrivateKey=EEGlnEPYJV//kbvvIqxKkQwOiS+UENyPncC4bF46ong=
ListenPort=51820

[WireGuardPeer]
PublicKey=RDf+LSpeEre7YEIKaxg+wbpsNV7du+ktR99uBEtIiCA=
AllowedIPs=fd31:bf08:57cb::/48,192.168.26.0/24
Endpoint=wireguard.example.com:51820
 

SEE ALSO

systemd(1), systemd-networkd(8), systemd.link(5), systemd.network(5)  

NOTES

1.
Linux Ethernet Bonding Driver HOWTO
https://www.kernel.org/doc/Documentation/networking/bonding.txt
2.
RFC 2784
https://tools.ietf.org/html/rfc2784
3.
IEEE 802.1Q
http://www.ieee802.org/1/pages/802.1Q.html
4.
VRF
https://www.kernel.org/doc/Documentation/networking/vrf.txt
5.
(DVOE)
https://en.wikipedia.org/wiki/Distributed_Overlay_Virtual_Ethernet
6.
VXLAN Group Policy
https://tools.ietf.org/html/draft-smith-vxlan-group-policy
7.
Type of Service in the Internet Protocol Suite
http://tools.ietf.org/html/rfc1349
8.
RFC 6437
https://tools.ietf.org/html/rfc6437
9.
RFC 2460
https://tools.ietf.org/html/rfc2460
10.
RFC 2473
https://tools.ietf.org/html/rfc2473#section-4.1.1
11.
ip-xfrm --- transform configuration
http://man7.org/linux/man-pages/man8/ip-xfrm.8.html


 

Index

NAME
SYNOPSIS
DESCRIPTION
SUPPORTED NETDEV KINDS
[MATCH] SECTION OPTIONS
[NETDEV] SECTION OPTIONS
[BRIDGE] SECTION OPTIONS
[VLAN] SECTION OPTIONS
[MACVLAN] SECTION OPTIONS
[MACVTAP] SECTION OPTIONS
[IPVLAN] SECTION OPTIONS
[VXLAN] SECTION OPTIONS
[GENEVE] SECTION OPTIONS
[TUNNEL] SECTION OPTIONS
[PEER] SECTION OPTIONS
[VXCAN] SECTION OPTIONS
[TUN] SECTION OPTIONS
[TAP] SECTION OPTIONS
[WIREGUARD] SECTION OPTIONS
[WIREGUARDPEER] SECTION OPTIONS
[BOND] SECTION OPTIONS
EXAMPLE
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:54 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.KILL

SYSTEMD.KILL

Section: systemd.kill (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.kill - Process killing procedure configuration  

SYNOPSIS

service.service, socket.socket, mount.mount, swap.swap, scope.scope  

DESCRIPTION

Unit configuration files for services, sockets, mount points, swap devices and scopes share a subset of configuration options which define the killing procedure of processes belonging to the unit.

This man page lists the configuration options shared by these five unit types. See systemd.unit(5) for the common options shared by all unit configuration files, and systemd.service(5), systemd.socket(5), systemd.swap(5), systemd.mount(5) and systemd.scope(5) for more information on the configuration file options specific to each unit type.

The kill procedure configuration options are configured in the [Service], [Socket], [Mount] or [Swap] section, depending on the unit type.  

OPTIONS

KillMode=

Specifies how processes of this unit shall be killed. One of control-group, process, mixed, none.

If set to control-group, all remaining processes in the control group of this unit will be killed on unit stop (for services: after the stop command is executed, as configured with ExecStop=). If set to process, only the main process itself is killed. If set to mixed, the SIGTERM signal (see below) is sent to the main process while the subsequent SIGKILL signal (see below) is sent to all remaining processes of the unit's control group. If set to none, no process is killed. In this case, only the stop command will be executed on unit stop, but no process be killed otherwise. Processes remaining alive after stop are left in their control group and the control group continues to exist after stop unless it is empty.

Processes will first be terminated via SIGTERM (unless the signal to send is changed via KillSignal=). Optionally, this is immediately followed by a SIGHUP (if enabled with SendSIGHUP=). If then, after a delay (configured via the TimeoutStopSec= option), processes still remain, the termination request is repeated with the SIGKILL signal (unless this is disabled via the SendSIGKILL= option). See kill(2) for more information.

Defaults to control-group.

KillSignal=

Specifies which signal to use when killing a service. This controls the signal that is sent as first step of shutting down a unit (see above), and is usually followed by SIGKILL (see above and below). For a list of valid signals, see signal(7). Defaults to SIGTERM.

Note that, right after sending the signal specified in this setting, systemd will always send SIGCONT, to ensure that even suspended tasks can be terminated cleanly.

SendSIGHUP=

Specifies whether to send SIGHUP to remaining processes immediately after sending the signal configured with KillSignal=. This is useful to indicate to shells and shell-like programs that their connection has been severed. Takes a boolean value. Defaults to "no".

SendSIGKILL=

Specifies whether to send SIGKILL to remaining processes after a timeout, if the normal shutdown procedure left processes of the service around. Takes a boolean value. Defaults to "yes".
 

SEE ALSO

systemd(1), systemctl(1), journalctl(8), systemd.unit(5), systemd.service(5), systemd.socket(5), systemd.swap(5), systemd.mount(5), systemd.exec(5), systemd.directives(7), kill(2), signal(7)


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:54 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.LINK

SYSTEMD.LINK

Section: systemd.link (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.link - Network device configuration  

SYNOPSIS

link.link  

DESCRIPTION

Network link configuration is performed by the net_setup_link udev builtin.

The link files are read from the files located in the system network directory /lib/systemd/network, the volatile runtime network directory /run/systemd/network, and the local administration network directory /etc/systemd/network. Link files must have the extension .link; other extensions are ignored. All link files are collectively sorted and processed in lexical order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in /etc have the highest priority, files in /run take precedence over files with the same name in /lib. This can be used to override a system-supplied link file with a local file if needed. As a special case, an empty file (file size 0) or symlink with the same name pointing to /dev/null disables the configuration file entirely (it is "masked").

The link file contains a "[Match]" section, which determines if a given link file may be applied to a given device, as well as a "[Link]" section specifying how the device should be configured. The first (in lexical order) of the link files that matches a given device is applied. Note that a default file 99-default.link is shipped by the system. Any user-supplied .link should hence have a lexically earlier name to be considered at all.

See udevadm(8) for diagnosing problems with .link files.  

[MATCH] SECTION OPTIONS

A link file is said to match a device if each of the entries in the "[Match]" section matches, or if the section is empty. The following keys are accepted:

MACAddress=

The hardware address.

OriginalName=

A whitespace-separated list of shell-style globs matching the device name, as exposed by the udev property "INTERFACE". This cannot be used to match on names that have already been changed from userspace. Caution is advised when matching on kernel-assigned names, as they are known to be unstable between reboots.

Path=

A whitespace-separated list of shell-style globs matching the persistent path, as exposed by the udev property "ID_PATH".

Driver=

A whitespace-separated list of shell-style globs matching the driver currently bound to the device, as exposed by the udev property "DRIVER" of its parent device, or if that is not set, the driver as exposed by "ethtool -i" of the device itself.

Type=

A whitespace-separated list of shell-style globs matching the device type, as exposed by the udev property "DEVTYPE".

Host=

Matches against the hostname or machine ID of the host. See "ConditionHost=" in systemd.unit(5) for details.

Virtualization=

Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation. See "ConditionVirtualization=" in systemd.unit(5) for details.

KernelCommandLine=

Checks whether a specific kernel command line option is set (or if prefixed with the exclamation mark unset). See "ConditionKernelCommandLine=" in systemd.unit(5) for details.

KernelVersion=

Checks whether the kernel version (as reported by uname -r) matches a certain expression (or if prefixed with the exclamation mark does not match it). See "ConditionKernelVersion=" in systemd.unit(5) for details.

Architecture=

Checks whether the system is running on a specific architecture. See "ConditionArchitecture=" in systemd.unit(5) for details.
 

[LINK] SECTION OPTIONS

The "[Link]" section accepts the following keys:

Description=

A description of the device.

Alias=

The "ifalias" is set to this value.

MACAddressPolicy=

The policy by which the MAC address should be set. The available policies are:

"persistent"

If the hardware has a persistent MAC address, as most hardware should, and if it is used by the kernel, nothing is done. Otherwise, a new MAC address is generated which is guaranteed to be the same on every boot for the given machine and the given device, but which is otherwise random. This feature depends on ID_NET_NAME_* properties to exist for the link. On hardware where these properties are not set, the generation of a persistent MAC address will fail.

"random"

If the kernel is using a random MAC address, nothing is done. Otherwise, a new address is randomly generated each time the device appears, typically at boot. Either way, the random address will have the "unicast" and "locally administered" bits set.

"none"

Keeps the MAC address assigned by the kernel.

MACAddress=

The MAC address to use, if no "MACAddressPolicy=" is specified.

NamePolicy=

An ordered, space-separated list of policies by which the interface name should be set. "NamePolicy" may be disabled by specifying "net.ifnames=0" on the kernel command line. Each of the policies may fail, and the first successful one is used. The name is not set directly, but is exported to udev as the property "ID_NET_NAME", which is, by default, used by a udev rule to set "NAME". If the name has already been set by userspace, no renaming is performed. The available policies are:

"kernel"

If the kernel claims that the name it has set for a device is predictable, then no renaming is performed.

"database"

The name is set based on entries in the udev's Hardware Database with the key "ID_NET_NAME_FROM_DATABASE".

"onboard"

The name is set based on information given by the firmware for on-board devices, as exported by the udev property "ID_NET_NAME_ONBOARD".

"slot"

The name is set based on information given by the firmware for hot-plug devices, as exported by the udev property "ID_NET_NAME_SLOT".

"path"

The name is set based on the device's physical location, as exported by the udev property "ID_NET_NAME_PATH".

"mac"

The name is set based on the device's persistent MAC address, as exported by the udev property "ID_NET_NAME_MAC".

Name=

The interface name to use in case all the policies specified in NamePolicy= fail, or in case NamePolicy= is missing or disabled.

Note that specifying a name that the kernel might use for another interface (for example "eth0") is dangerous because the name assignment done by udev will race with the assignment done by the kernel, and only one interface may use the name. Depending on the order of operations, either udev or the kernel will win, making the naming unpredictable. It is best to use some different prefix, for example "internal0"/"external0" or "lan0"/"lan1"/"lan3".

MTUBytes=

The maximum transmission unit in bytes to set for the device. The usual suffixes K, M, G, are supported and are understood to the base of 1024.

BitsPerSecond=

The speed to set for the device, the value is rounded down to the nearest Mbps. The usual suffixes K, M, G, are supported and are understood to the base of 1000.

Duplex=

The duplex mode to set for the device. The accepted values are "half" and "full".

AutoNegotiation=

Enables or disables automatic negotiation of transmission parameters. Autonegotiation is a procedure by which two connected ethernet devices choose common transmission parameters, such as speed, duplex mode, and flow control. Takes a boolean value. Unset by default, which means that the kernel default will be used.

Note that if autonegotiation is enabled, speed and duplex settings are read-only. If autonegotation is disabled, speed and duplex settings are writable if the driver supports multiple link modes.

WakeOnLan=

The Wake-on-LAN policy to set for the device. The supported values are:

"phy"

Wake on PHY activity.

"unicast"

Wake on unicast messages.

"multicast"

Wake on multicast messages.

"broadcast"

Wake on broadcast messages.

"arp"

Wake on ARP.

"magic"

Wake on receipt of a magic packet.

"secureon"

Enable secureon(tm) password for MagicPacket(tm).

"off"

Never wake.

Defaults to "off".

Port=

The port option is used to select the device port. The supported values are:

"tp"

An Ethernet interface using Twisted-Pair cable as the medium.

"aui"

Attachment Unit Interface (AUI). Normally used with hubs.

"bnc"

An Ethernet interface using BNC connectors and co-axial cable.

"mii"

An Ethernet interface using a Media Independent Interface (MII).

"fibre"

An Ethernet interface using Optical Fibre as the medium.

TCPSegmentationOffload=

The TCP Segmentation Offload (TSO) when true enables TCP segmentation offload. Takes a boolean value. Defaults to "unset".

TCP6SegmentationOffload=

The TCP6 Segmentation Offload (tx-tcp6-segmentation) when true enables TCP6 segmentation offload. Takes a boolean value. Defaults to "unset".

GenericSegmentationOffload=

The Generic Segmentation Offload (GSO) when true enables generic segmentation offload. Takes a boolean value. Defaults to "unset".

UDPSegmentationOffload=

The UDP Segmentation Offload (USO) when true enables UDP segmentation offload. Takes a boolean value. Defaults to "unset".

GenericReceiveOffload=

The Generic Receive Offload (GRO) when true enables generic receive offload. Takes a boolean value. Defaults to "unset".

LargeReceiveOffload=

The Large Receive Offload (LRO) when true enables large receive offload. Takes a boolean value. Defaults to "unset".
 

EXAMPLES

Example 1. /lib/systemd/network/99-default.link

The link file 99-default.link that is shipped with systemd defines the default naming policy for links.

[Link]
NamePolicy=kernel database onboard slot path
MACAddressPolicy=persistent

Example 2. /etc/systemd/network/10-dmz.link

This example assigns the fixed name "dmz0" to the interface with the MAC address 00:a0:de:63:7a:e6:

[Match]
MACAddress=00:a0:de:63:7a:e6

[Link]
Name=dmz0

Example 3. /etc/systemd/network/10-internet.link

This example assigns the fixed name "internet0" to the interface with the device path "pci-0000:00:1a.0-*":

[Match]
Path=pci-0000:00:1a.0-*

[Link]
Name=internet0

Example 4. /etc/systemd/network/25-wireless.link

Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings.

[Match]
MACAddress=12:34:56:78:9a:bc
Driver=brcmsmac
Path=pci-0000:02:00.0-*
Type=wlan
Virtualization=no
Host=my-laptop
Architecture=x86-64

[Link]
Name=wireless0
MTUBytes=1450
BitsPerSecond=10M
WakeOnLan=magic
MACAddress=cb:a9:87:65:43:21
 

SEE ALSO

systemd-udevd.service(8), udevadm(8), systemd.netdev(5), systemd.network(5)


 

Index

NAME
SYNOPSIS
DESCRIPTION
[MATCH] SECTION OPTIONS
[LINK] SECTION OPTIONS
EXAMPLES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:55 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.SOCKET

SYSTEMD.SOCKET

Section: systemd.socket (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.socket - Socket unit configuration  

SYNOPSIS

socket.socket  

DESCRIPTION

A unit configuration file whose name ends in ".socket" encodes information about an IPC or network socket or a file system FIFO controlled and supervised by systemd, for socket-based activation.

This man page lists the configuration options specific to this unit type. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The socket specific configuration options are configured in the [Socket] section.

Additional options are listed in systemd.exec(5), which define the execution environment the ExecStartPre=, ExecStartPost=, ExecStopPre= and ExecStopPost= commands are executed in, and in systemd.kill(5), which define the way the processes are terminated, and in systemd.resource-control(5), which configure resource control settings for the processes of the socket.

For each socket file, a matching service file must exist, describing the service to start on incoming traffic on the socket (see systemd.service(5) for more information about .service files). The name of the .service unit is by default the same as the name of the .socket unit, but can be altered with the Service= option described below. Depending on the setting of the Accept= option described below, this .service unit must either be named like the .socket unit, but with the suffix replaced, unless overridden with Service=; or it must be a template unit named the same way. Example: a socket file foo.socket needs a matching service foo.service if Accept=false is set. If Accept=true is set, a service template file foo@.service must exist from which services are instantiated for each incoming connection.

No implicit WantedBy= or RequiredBy= dependency from the socket to the service is added. This means that the service may be started without the socket, in which case it must be able to open sockets by itself. To prevent this, an explicit Requires= dependency may be added.

Socket units may be used to implement on-demand starting of services, as well as parallelized starting of services. See the blog stories linked at the end for an introduction.

Note that the daemon software configured for socket activation with socket units needs to be able to accept sockets from systemd, either via systemd's native socket passing interface (see sd_listen_fds(3) for details) or via the traditional inetd(8)-style socket passing (i.e. sockets passed in via standard input and output, using StandardInput=socket in the service file).  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• Socket units automatically gain a Before= dependency on the service units they activate.

• Socket units referring to file system paths (such as AF_UNIX sockets or FIFOs) implicitly gain Requires= and After= dependencies on all mount units necessary to access those paths.

• Socket units using the BindToDevice= setting automatically gain a BindsTo= and After= dependency on the device unit encapsulating the specified network interface.

Additional implicit dependencies may be added as result of execution and resource control parameters as documented in systemd.exec(5) and systemd.resource-control(5).  

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Socket units automatically gain a Before= dependency on sockets.target.

• Socket units automatically gain a pair of After= and Requires= dependency on sysinit.target, and a pair of Before= and Conflicts= dependencies on shutdown.target. These dependencies ensure that the socket unit is started before normal services at boot, and is stopped on shutdown. Only sockets involved with early boot or late system shutdown should disable DefaultDependencies= option.
 

OPTIONS

Socket files must include a [Socket] section, which carries information about the socket or FIFO 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.exec(5) and systemd.kill(5). The options specific to the [Socket] section of socket units are the following:

ListenStream=, ListenDatagram=, ListenSequentialPacket=

Specifies an address to listen on for a stream (SOCK_STREAM), datagram (SOCK_DGRAM), or sequential packet (SOCK_SEQPACKET) socket, respectively. The address can be written in various formats:

If the address starts with a slash ("/"), it is read as file system socket in the AF_UNIX socket family.

If the address starts with an at symbol ("@"), it is read as abstract namespace socket in the AF_UNIX family. The "@" is replaced with a NUL character before binding. For details, see unix(7).

If the address string is a single number, it is read as port number to listen on via IPv6. Depending on the value of BindIPv6Only= (see below) this might result in the service being available via both IPv6 and IPv4 (default) or just via IPv6.

If the address string is a string in the format v.w.x.y:z, it is read as IPv4 specifier for listening on an address v.w.x.y on a port z.

If the address string is a string in the format [x]:y, it is read as IPv6 address x on a port y. Note that this might make the service available via IPv4, too, depending on the BindIPv6Only= setting (see below).

If the address string is a string in the format "vsock:x:y", it is read as CID "x" on a port "y" address in the AF_VSOCK family. The CID is a unique 32-bit integer identifier in AF_VSOCK analogous to an IP address. Specifying the CID is optional, and may be set to the empty string.

Note that SOCK_SEQPACKET (i.e. ListenSequentialPacket=) is only available for AF_UNIX sockets. SOCK_STREAM (i.e. ListenStream=) when used for IP sockets refers to TCP sockets, SOCK_DGRAM (i.e. ListenDatagram=) to UDP.

These options may be specified more than once, in which case incoming traffic on any of the sockets will trigger service activation, and all listed sockets will be passed to the service, regardless of whether there is incoming traffic on them or not. If the empty string is assigned to any of these options, the list of addresses to listen on is reset, all prior uses of any of these options will have no effect.

It is also possible to have more than one socket unit for the same service when using Service=, and the service will receive all the sockets configured in all the socket units. Sockets configured in one unit are passed in the order of configuration, but no ordering between socket units is specified.

If an IP address is used here, it is often desirable to listen on it before the interface it is configured on is up and running, and even regardless of whether it will be up and running at any point. To deal with this, it is recommended to set the FreeBind= option described below.

ListenFIFO=

Specifies a file system FIFO to listen on. This expects an absolute file system path as argument. Behavior otherwise is very similar to the ListenDatagram= directive above.

ListenSpecial=

Specifies a special file in the file system to listen on. This expects an absolute file system path as argument. Behavior otherwise is very similar to the ListenFIFO= directive above. Use this to open character device nodes as well as special files in /proc and /sys.

ListenNetlink=

Specifies a Netlink family to create a socket for to listen on. This expects a short string referring to the AF_NETLINK family name (such as audit or kobject-uevent) as argument, optionally suffixed by a whitespace followed by a multicast group integer. Behavior otherwise is very similar to the ListenDatagram= directive above.

ListenMessageQueue=

Specifies a POSIX message queue name to listen on. This expects a valid message queue name (i.e. beginning with /). Behavior otherwise is very similar to the ListenFIFO= directive above. On Linux message queue descriptors are actually file descriptors and can be inherited between processes.

ListenUSBFunction=

Specifies a m[blue]USB FunctionFSm[][1] endpoints location to listen on, for implementation of USB gadget functions. This expects an absolute file system path of functionfs mount point as the argument. Behavior otherwise is very similar to the ListenFIFO= directive above. Use this to open the FunctionFS endpoint ep0. When using this option, the activated service has to have the USBFunctionDescriptors= and USBFunctionStrings= options set.

SocketProtocol=

Takes a one of udplite or sctp. Specifies a socket protocol (IPPROTO_UDPLITE) UDP-Lite (IPPROTO_SCTP) SCTP socket respectively.

BindIPv6Only=

Takes a one of default, both or ipv6-only. Controls the IPV6_V6ONLY socket option (see ipv6(7) for details). If both, IPv6 sockets bound will be accessible via both IPv4 and IPv6. If ipv6-only, they will be accessible via IPv6 only. If default (which is the default, surprise!), the system wide default setting is used, as controlled by /proc/sys/net/ipv6/bindv6only, which in turn defaults to the equivalent of both.

Backlog=

Takes an unsigned integer argument. Specifies the number of connections to queue that have not been accepted yet. This setting matters only for stream and sequential packet sockets. See listen(2) for details. Defaults to SOMAXCONN (128).

BindToDevice=

Specifies a network interface name to bind this socket to. If set, traffic will only be accepted from the specified network interfaces. This controls the SO_BINDTODEVICE socket option (see socket(7) for details). If this option is used, an implicit dependency from this socket unit on the network interface device unit (systemd.device(5) is created. Note that setting this parameter might result in additional dependencies to be added to the unit (see above).

SocketUser=, SocketGroup=

Takes a UNIX user/group name. When specified, all AF_UNIX sockets and FIFO nodes in the file system are owned by the specified user and group. If unset (the default), the nodes are owned by the root user/group (if run in system context) or the invoking user/group (if run in user context). If only a user is specified but no group, then the group is derived from the user's default group.

SocketMode=

If listening on a file system socket or FIFO, this option specifies the file system access mode used when creating the file node. Takes an access mode in octal notation. Defaults to 0666.

DirectoryMode=

If listening on a file system socket or FIFO, the parent directories are automatically created if needed. This option specifies the file system access mode used when creating these directories. Takes an access mode in octal notation. Defaults to 0755.

Accept=

Takes a boolean argument. If true, a service instance is spawned for each incoming connection and only the connection socket is passed to it. If false, all listening sockets themselves are passed to the started service unit, and only one service unit is spawned for all connections (also see above). This value is ignored for datagram sockets and FIFOs where a single service unit unconditionally handles all incoming traffic. Defaults to false. For performance reasons, it is recommended to write new daemons only in a way that is suitable for Accept=false. A daemon listening on an AF_UNIX socket may, but does not need to, call close(2) on the received socket before exiting. However, it must not unlink the socket from a file system. It should not invoke shutdown(2) on sockets it got with Accept=false, but it may do so for sockets it got with Accept=true set. Setting Accept=true is mostly useful to allow daemons designed for usage with inetd(8) to work unmodified with systemd socket activation.

For IPv4 and IPv6 connections, the REMOTE_ADDR environment variable will contain the remote IP address, and REMOTE_PORT will contain the remote port. This is the same as the format used by CGI. For SOCK_RAW, the port is the IP protocol.

Writable=

Takes a boolean argument. May only be used in conjunction with ListenSpecial=. If true, the specified special file is opened in read-write mode, if false, in read-only mode. Defaults to false.

MaxConnections=

The maximum number of connections to simultaneously run services instances for, when Accept=true is set. If more concurrent connections are coming in, they will be refused until at least one existing connection is terminated. This setting has no effect on sockets configured with Accept=false or datagram sockets. Defaults to 64.

MaxConnectionsPerSource=

The maximum number of connections for a service per source IP address. This is very similar to the MaxConnections= directive above. Disabled by default.

KeepAlive=

Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message after 2h (depending on the configuration of /proc/sys/net/ipv4/tcp_keepalive_time) for all TCP streams accepted on this socket. This controls the SO_KEEPALIVE socket option (see socket(7) and the m[blue]TCP Keepalive HOWTOm[][2] for details.) Defaults to false.

KeepAliveTimeSec=

Takes time (in seconds) as argument. The connection needs to remain idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE socket option (see socket(7) and the m[blue]TCP Keepalive HOWTOm[][2] for details.) Defaults value is 7200 seconds (2 hours).

KeepAliveIntervalSec=

Takes time (in seconds) as argument between individual keepalive probes, if the socket option SO_KEEPALIVE has been set on this socket. This controls the TCP_KEEPINTVL socket option (see socket(7) and the m[blue]TCP Keepalive HOWTOm[][2] for details.) Defaults value is 75 seconds.

KeepAliveProbes=

Takes an integer as argument. It is the number of unacknowledged probes to send before considering the connection dead and notifying the application layer. This controls the TCP_KEEPCNT socket option (see socket(7) and the m[blue]TCP Keepalive HOWTOm[][2] for details.) Defaults value is 9.

NoDelay=

Takes a boolean argument. TCP Nagle's algorithm works by combining a number of small outgoing messages, and sending them all at once. This controls the TCP_NODELAY socket option (see tcp(7) Defaults to false.

Priority=

Takes an integer argument controlling the priority for all traffic sent from this socket. This controls the SO_PRIORITY socket option (see socket(7) for details.).

DeferAcceptSec=

Takes time (in seconds) as argument. If set, the listening process will be awakened only when data arrives on the socket, and not immediately when connection is established. When this option is set, the TCP_DEFER_ACCEPT socket option will be used (see tcp(7)), and the kernel will ignore initial ACK packets without any data. The argument specifies the approximate amount of time the kernel should wait for incoming data before falling back to the normal behavior of honoring empty ACK packets. This option is beneficial for protocols where the client sends the data first (e.g. HTTP, in contrast to SMTP), because the server process will not be woken up unnecessarily before it can take any action.

If the client also uses the TCP_DEFER_ACCEPT option, the latency of the initial connection may be reduced, because the kernel will send data in the final packet establishing the connection (the third packet in the "three-way handshake").

Disabled by default.

ReceiveBuffer=, SendBuffer=

Takes an integer argument controlling the receive or send buffer sizes of this socket, respectively. This controls the SO_RCVBUF and SO_SNDBUF socket options (see socket(7) for details.). The usual suffixes K, M, G are supported and are understood to the base of 1024.

IPTOS=

Takes an integer argument controlling the IP Type-Of-Service field for packets generated from this socket. This controls the IP_TOS socket option (see ip(7) for details.). Either a numeric string or one of low-delay, throughput, reliability or low-cost may be specified.

IPTTL=

Takes an integer argument controlling the IPv4 Time-To-Live/IPv6 Hop-Count field for packets generated from this socket. This sets the IP_TTL/IPV6_UNICAST_HOPS socket options (see ip(7) and ipv6(7) for details.)

Mark=

Takes an integer value. Controls the firewall mark of packets generated by this socket. This can be used in the firewall logic to filter packets from this socket. This sets the SO_MARK socket option. See iptables(8) for details.

ReusePort=

Takes a boolean value. If true, allows multiple bind(2)s to this TCP or UDP port. This controls the SO_REUSEPORT socket option. See socket(7) for details.

SmackLabel=, SmackLabelIPIn=, SmackLabelIPOut=

Takes a string value. Controls the extended attributes "security.SMACK64", "security.SMACK64IPIN" and "security.SMACK64IPOUT", respectively, i.e. the security label of the FIFO, or the security label for the incoming or outgoing connections of the socket, respectively. See m[blue]Smack.txtm[][3] for details.

SELinuxContextFromNet=

Takes a boolean argument. When true, systemd will attempt to figure out the SELinux label used for the instantiated service from the information handed by the peer over the network. Note that only the security level is used from the information provided by the peer. Other parts of the resulting SELinux context originate from either the target binary that is effectively triggered by socket unit or from the value of the SELinuxContext= option. This configuration option only affects sockets with Accept= mode set to "true". Also note that this option is useful only when MLS/MCS SELinux policy is deployed. Defaults to "false".

PipeSize=

Takes a size in bytes. Controls the pipe buffer size of FIFOs configured in this socket unit. See fcntl(2) for details. The usual suffixes K, M, G are supported and are understood to the base of 1024.

MessageQueueMaxMessages=, MessageQueueMessageSize=

These two settings take integer values and control the mq_maxmsg field or the mq_msgsize field, respectively, when creating the message queue. Note that either none or both of these variables need to be set. See mq_setattr(3) for details.

FreeBind=

Takes a boolean value. Controls whether the socket can be bound to non-local IP addresses. This is useful to configure sockets listening on specific IP addresses before those IP addresses are successfully configured on a network interface. This sets the IP_FREEBIND socket option. For robustness reasons it is recommended to use this option whenever you bind a socket to a specific IP address. Defaults to false.

Transparent=

Takes a boolean value. Controls the IP_TRANSPARENT socket option. Defaults to false.

Broadcast=

Takes a boolean value. This controls the SO_BROADCAST socket option, which allows broadcast datagrams to be sent from this socket. Defaults to false.

PassCredentials=

Takes a boolean value. This controls the SO_PASSCRED socket option, which allows AF_UNIX sockets to receive the credentials of the sending process in an ancillary message. Defaults to false.

PassSecurity=

Takes a boolean value. This controls the SO_PASSSEC socket option, which allows AF_UNIX sockets to receive the security context of the sending process in an ancillary message. Defaults to false.

TCPCongestion=

Takes a string value. Controls the TCP congestion algorithm used by this socket. Should be one of "westwood", "veno", "cubic", "lp" or any other available algorithm supported by the IP stack. This setting applies only to stream sockets.

ExecStartPre=, ExecStartPost=

Takes one or more command lines, which are executed before or after the listening sockets/FIFOs are created and bound, respectively. The first token of the command line must be an absolute filename, then followed by arguments for the process. Multiple command lines may be specified following the same scheme as used for ExecStartPre= of service unit files.

ExecStopPre=, ExecStopPost=

Additional commands that are executed before or after the listening sockets/FIFOs are closed and removed, respectively. Multiple command lines may be specified following the same scheme as used for ExecStartPre= of service unit files.

TimeoutSec=

Configures the time to wait for the commands specified in ExecStartPre=, ExecStartPost=, ExecStopPre= and ExecStopPost= to finish. If a command does not exit within the configured time, the socket will be considered failed and be shut down again. All commands still running will be terminated forcibly via SIGTERM, and after another delay of this time with SIGKILL. (See KillMode= in systemd.kill(5).) Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass "0" to disable the timeout logic. Defaults to DefaultTimeoutStartSec= from the manager configuration file (see systemd-system.conf(5)).

Service=

Specifies the service unit name to activate on incoming traffic. This setting is only allowed for sockets with Accept=no. It defaults to the service that bears the same name as the socket (with the suffix replaced). In most cases, it should not be necessary to use this option. Note that setting this parameter might result in additional dependencies to be added to the unit (see above).

RemoveOnStop=

Takes a boolean argument. If enabled, any file nodes created by this socket unit are removed when it is stopped. This applies to AF_UNIX sockets in the file system, POSIX message queues, FIFOs, as well as any symlinks to them configured with Symlinks=. Normally, it should not be necessary to use this option, and is not recommended as services might continue to run after the socket unit has been terminated and it should still be possible to communicate with them via their file system node. Defaults to off.

Symlinks=

Takes a list of file system paths. The specified paths will be created as symlinks to the AF_UNIX socket path or FIFO path of this socket unit. If this setting is used, only one AF_UNIX socket in the file system or one FIFO may be configured for the socket unit. Use this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty list.

FileDescriptorName=

Assigns a name to all file descriptors this socket unit encapsulates. This is useful to help activated services identify specific file descriptors, if multiple fds are passed. Services may use the sd_listen_fds_with_names(3) call to acquire the names configured for the received file descriptors. Names may contain any ASCII character, but must exclude control characters and ":", and must be at most 255 characters in length. If this setting is not used, the file descriptor name defaults to the name of the socket unit, including its .socket suffix.

TriggerLimitIntervalSec=, TriggerLimitBurst=

Configures a limit on how often this socket unit my be activated within a specific time interval. The TriggerLimitIntervalSec= may be used to configure the length of the time interval in the usual time units "us", "ms", "s", "min", "h", ... and defaults to 2s (See systemd.time(7) for details on the various time units understood). The TriggerLimitBurst= setting takes a positive integer value and specifies the number of permitted activations per time interval, and defaults to 200 for Accept=yes sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20 activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this limit is enforced before the service activation is enqueued.

Check systemd.exec(5) and systemd.kill(5) for more settings.  

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), systemd.exec(5), systemd.kill(5), systemd.resource-control(5), systemd.service(5), systemd.directives(7), sd_listen_fds(3), sd_listen_fds_with_names(3)

For more extensive descriptions see the "systemd for Developers" series: m[blue]Socket Activationm[][4], m[blue]Socket Activation, part IIm[][5], m[blue]Converting inetd Servicesm[][6], m[blue]Socket Activated Internet Services and OS Containersm[][7].  

NOTES

1.
USB FunctionFS
https://www.kernel.org/doc/Documentation/usb/functionfs.txt
2.
TCP Keepalive HOWTO
http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/
3.
Smack.txt
https://www.kernel.org/doc/Documentation/security/Smack.txt
4.
Socket Activation
http://0pointer.de/blog/projects/socket-activation.html
5.
Socket Activation, part II
http://0pointer.de/blog/projects/socket-activation2.html
6.
Converting inetd Services
http://0pointer.de/blog/projects/inetd.html
7.
Socket Activated Internet Services and OS Containers
http://0pointer.de/blog/projects/socket-activated-containers.html


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
OPTIONS
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:55 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.DEVICE

SYSTEMD.DEVICE

Section: systemd.device (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.device - Device unit configuration  

SYNOPSIS

device.device  

DESCRIPTION

A unit configuration file whose name ends in ".device" encodes information about a device unit as exposed in the sysfs/udev(7) device tree.

This unit type has no specific options. See systemd.unit(5) 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.

systemd will dynamically create device units for all kernel devices that are marked with the "systemd" udev tag (by default all block and network devices, and a few others). This may be used to define dependencies between devices and other units. To tag a udev device, use "TAG+="systemd"" in the udev rules file, see udev(7) for details.

Device units are named after the /sys and /dev paths they control. Example: the device /dev/sda5 is exposed in systemd as dev-sda5.device. For details about the escaping logic used to convert a file system path to a unit name see systemd.unit(5).

Device units will be reloaded by systemd whenever the corresponding device generates a "changed" event. Other units can use ReloadPropagatedFrom= to react to that event  

IMPLICIT DEPENDENCIES

Many unit types automatically acquire dependencies on device units of devices they require. For example, .socket unit acquire dependencies on the device units of the network interface specified in BindToDevice=. Similar, swap and mount units acquire dependencies on the units encapsulating their backing block devices.  

DEFAULT DEPENDENCIES

There are no default dependencies for device units.  

THE UDEV DATABASE

Unit settings of device units may either be configured via unit files, or directly from the udev database. The following udev device properties are understood by the service manager:

SYSTEMD_WANTS=, SYSTEMD_USER_WANTS=

Adds dependencies of type Wants= from the device unit to the specified units. SYSTEMD_WANTS= is read by the system service manager, SYSTEMD_USER_WANTS= by user service manager instances. These properties may be used to activate arbitrary units when a specific device becomes available.

Note that this and the other udev device properties are not taken into account unless the device is tagged with the "systemd" tag in the udev database, because otherwise the device is not exposed as a systemd unit (see above).

Note that systemd will only act on Wants= dependencies when a device first becomes active. It will not act on them if they are added to devices that are already active. Use SYSTEMD_READY= (see below) to configure when a udev device shall be considered active, and thus when to trigger the dependencies.

The specified property value should be a space-separated list of valid unit names. If a unit template name is specified (that is, a unit name containing an "@" character indicating a unit name to use for multiple instantiation, but with an empty instance name following the "@"), it will be automatically instantiated by the device's "sysfs" path (that is: the path is escaped and inserted as instance name into the template unit name). This is useful in order to instantiate a specific template unit once for each device that appears and matches specific properties.

SYSTEMD_ALIAS=

Adds an additional alias name to the device unit. This must be an absolute path that is automatically transformed into a unit name. (See above.)

SYSTEMD_READY=

If set to 0, systemd will consider this device unplugged even if it shows up in the udev tree. If this property is unset or set to 1, the device will be considered plugged if it is visible in the udev tree.

This option is useful for devices that initially show up in an uninitialized state in the tree, and for which a "changed" event is generated the moment they are fully set up. Note that SYSTEMD_WANTS= (see above) is not acted on as long as SYSTEMD_READY=0 is set for a device.

ID_MODEL_FROM_DATABASE=, ID_MODEL=

If set, this property is used as description string for the device unit.
 

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), udev(7), systemd.directives(7)


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
THE UDEV DATABASE
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:55 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.DNSSD

SYSTEMD.DNSSD

Section: systemd.dnssd (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.dnssd - DNS-SD configuration  

SYNOPSIS

network_service.dnssd  

DESCRIPTION

DNS-SD setup is performed by systemd-resolved(8).

The main network service file must have the extension .dnssd; other extensions are ignored.

The .dnssd files are read from the files located in the system network directory /usr/lib/systemd/dnssd, the volatile runtime network directory /run/systemd/dnssd and the local administration network directory /etc/systemd/dnssd. All configuration files are collectively sorted and processed in lexical order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in /etc have the highest priority, files in /run take precedence over files with the same name in /lib. This can be used to override a system-supplied configuration file with a local file if needed.

Along with the network service file foo.dnssd, a "drop-in" directory foo.dnssd.d/ may exist. All files with the suffix ".conf" from this directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers.

In addition to /etc/systemd/dnssd, drop-in ".d" directories can be placed in /usr/lib/systemd/dnssd or /run/systemd/dnssd directories. Drop-in files in /etc take precedence over those in /run which in turn take precedence over those in /lib. Drop-in files under any of these directories take precedence over the main network service file wherever located. (Of course, since /run is temporary and /usr/lib is for vendors, it is unlikely drop-ins should be used in either of those places.)  

[SERVICE] SECTION OPTIONS

The network service file contains a "[Service]" section, which specifies a discoverable network service announced in a local network with Multicast DNS broadcasts.

Name=

An instance name of the network service as defined in the section 4.1.1 of m[blue]RFC 6763m[][1], e.g. "webserver".

The option supports simple specifier expansion. The following expansions are understood:


Table 1. Specifiers available

Specifier Meaning Details
"%m" Machine ID The machine ID of the running system, formatted as string. See machine-id(5) for more information.
"%b" Boot ID The boot ID of the running system, formatted as string. See random(4) for more information.
"%H" Host name The hostname of the running system.
"%v" Kernel release Identical to uname -r output.

Type=

A type of the network service as defined in the section 4.1.2 of m[blue]RFC 6763m[][1], e.g. "_http._tcp".

Port=

An IP port number of the network service.

Priority=

A priority number set in SRV resource records corresponding to the network service.

Weight=

A weight number set in SRV resource records corresponding to the network service.

TxtText=

A whitespace-separated list of arbitrary key/value pairs conveying additional information about the named service in the corresponding TXT resource record, e.g. "path=/portal/index.html". Keys and values can contain C-style escape sequences which get translated upon reading configuration files.

This option together with TxtData= may be specified more than once, in which case multiple TXT resource records will be created for the service. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect.

TxtData=

A whitespace-separated list of arbitrary key/value pairs conveying additional information about the named service in the corresponding TXT resource record where values are base64-encoded string representing any binary data, e.g. "data=YW55IGJpbmFyeSBkYXRhCg==". Keys can contain C-style escape sequences which get translated upon reading configuration files.

This option together with TxtText= may be specified more than once, in which case multiple TXT resource records will be created for the service. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect.

 

EXAMPLES

Example 1. HTTP service

# /etc/systemd/dnssd/http.dnssd
[Service]
Name=%H
Type=_http._tcp
Port=80
TxtText=path=/stats/index.html t=temperature_sensor

This makes the http server running on the host discoverable in the local network given MulticastDNS is enabled on the network interface.

Now the utility "systemd-resolve" should be able to resolve the service to the host's name:

$ systemd-resolve  --service meteo._http._tcp.local
meteo._http._tcp.local: meteo.local:80 [priority=0, weight=0]
                        169.254.208.106%senp0s21f0u2u4
                        fe80::213:3bff:fe49:8aa%senp0s21f0u2u4
                        path=/stats/index.html
                        t=temperature_sensor
                        (meteo/_http._tcp/local)

-- Information acquired via protocol mDNS/IPv6 in 4.0ms.
-- Data is authenticated: yes

"Avahi" running on a different host in the same local network should see the service as well:

$ avahi-browse -a -r
+ enp3s0 IPv6 meteo                                         Web Site             local
+ enp3s0 IPv4 meteo                                         Web Site             local
= enp3s0 IPv6 meteo                                         Web Site             local
   hostname = [meteo.local]
   address = [fe80::213:3bff:fe49:8aa]
   port = [80]
   txt = ["path=/stats/index.html" "t=temperature_sensor"]
= enp3s0 IPv4 meteo                                         Web Site             local
   hostname = [meteo.local]
   address = [169.254.208.106]
   port = [80]
   txt = ["path=/stats/index.html" "t=temperature_sensor"]
 

SEE ALSO

systemd(1), systemd-resolved.service(8)  

NOTES

1.
RFC 6763
https://tools.ietf.org/html/rfc6763


 

Index

NAME
SYNOPSIS
DESCRIPTION
[SERVICE] SECTION OPTIONS
EXAMPLES
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:55 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.EXEC

SYSTEMD.EXEC

Section: systemd.exec (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.exec - Execution environment configuration  

SYNOPSIS

service.service, socket.socket, mount.mount, swap.swap  

DESCRIPTION

Unit configuration files for services, sockets, mount points, and swap devices share a subset of configuration options which define the execution environment of spawned processes.

This man page lists the configuration options shared by these four unit types. See systemd.unit(5) for the common options of all unit configuration files, and systemd.service(5), systemd.socket(5), systemd.swap(5), and systemd.mount(5) for more information on the specific unit configuration files. The execution specific configuration options are configured in the [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type.

In addition, options which control resources through Linux Control Groups (cgroups) are listed in systemd.resource-control(5). Those options complement options listed here.  

IMPLICIT DEPENDENCIES

A few execution parameters result in additional, automatic dependencies to be added:

• Units with WorkingDirectory=, RootDirectory=, RootImage=, RuntimeDirectory=, StateDirectory=, CacheDirectory=, LogsDirectory= or ConfigurationDirectory= set automatically gain dependencies of type Requires= and After= on all mount units required to access the specified paths. This is equivalent to having them listed explicitly in RequiresMountsFor=.

• Similar, units with PrivateTmp= enabled automatically get mount unit dependencies for all mounts required to access /tmp and /var/tmp. They will also gain an automatic After= dependency on systemd-tmpfiles-setup.service(8).

• Units whose standard output or error output is connected to journal, syslog or kmsg (or their combinations with console output, see below) automatically acquire dependencies of type After= on systemd-journald.socket.
 

PATHS

WorkingDirectory=

Takes a directory path relative to the service's root directory specified by RootDirectory=, or the special value "~". Sets the working directory for executed processes. If set to "~", the home directory of the user specified in User= is used. If not set, defaults to the root directory when systemd is running as a system instance and the respective user's home directory if run as user. If the setting is prefixed with the "-" character, a missing working directory is not considered fatal. If RootDirectory=/RootImage= is not set, then WorkingDirectory= is relative to the root of the system running the service manager. Note that setting this parameter might result in additional dependencies to be added to the unit (see above).

RootDirectory=

Takes a directory path relative to the host's root directory (i.e. the root of the system running the service manager). Sets the root directory for executed processes, with the chroot(2) system call. If this is used, it must be ensured that the process binary and all its auxiliary files are available in the chroot() jail. Note that setting this parameter might result in additional dependencies to be added to the unit (see above).

The MountAPIVFS= and PrivateUsers= settings are particularly useful in conjunction with RootDirectory=. For details, see below.

RootImage=

Takes a path to a block device node or regular file as argument. This call is similar to RootDirectory= however mounts a file system hierarchy from a block device node or loopback file instead of a directory. The device node or file system image file needs to contain a file system without a partition table, or a file system within an MBR/MS-DOS or GPT partition table with only a single Linux-compatible partition, or a set of file systems within a GPT partition table that follows the m[blue]Discoverable Partitions Specificationm[][1].

MountAPIVFS=

Takes a boolean argument. If on, a private mount namespace for the unit's processes is created and the API file systems /proc, /sys, and /dev are mounted inside of it, unless they are already mounted. Note that this option has no effect unless used in conjunction with RootDirectory=/RootImage= as these three mounts are generally mounted in the host anyway, and unless the root directory is changed, the private mount namespace will be a 1:1 copy of the host's, and include these three mounts. Note that the /dev file system of the host is bind mounted if this option is used without PrivateDevices=. To run the service with a private, minimal version of /dev/, combine this option with PrivateDevices=.

BindPaths=, BindReadOnlyPaths=

Configures unit-specific bind mounts. A bind mount makes a particular file or directory available at an additional place in the unit's view of the file system. Any bind mounts created with this option are specific to the unit, and are not visible in the host's mount table. This option expects a whitespace separated list of bind mount definitions. Each definition consists of a colon-separated triple of source path, destination path and option string, where the latter two are optional. If only a source path is specified the source and destination is taken to be the same. The option string may be either "rbind" or "norbind" for configuring a recursive or non-recursive bind mount. If the destination path is omitted, the option string must be omitted too.

BindPaths= creates regular writable bind mounts (unless the source file system mount is already marked read-only), while BindReadOnlyPaths= creates read-only bind mounts. These settings may be used more than once, each usage appends to the unit's list of bind mounts. If the empty string is assigned to either of these two options the entire list of bind mounts defined prior to this is reset. Note that in this case both read-only and regular bind mounts are reset, regardless which of the two settings is used.

This option is particularly useful when RootDirectory=/RootImage= is used. In this case the source path refers to a path on the host file system, while the destination path refers to a path below the root directory of the unit.

 

CREDENTIALS

User=, Group=

Set the UNIX user or group that the processes are executed as, respectively. Takes a single user or group name, or a numeric ID as argument. For system services (services run by the system service manager, i.e. managed by PID 1) and for user services of the root user (services managed by root's instance of systemd --user), the default is "root", but User= may be used to specify a different user. For user services of any other user, switching user identity is not permitted, hence the only valid setting is the same user the user's service manager is running as. If no group is set, the default group of the user is used. This setting does not affect commands whose command line is prefixed with "+".

Note that restrictions on the user/group name syntax are enforced: the specified name must consist only of the characters a-z, A-Z, 0-9, "_" and "-", except for the first character which must be one of a-z, A-Z or "_" (i.e. numbers and "-" are not permitted as first character). The user/group name must have at least one character, and at most 31. These restrictions are enforced in order to avoid ambiguities and to ensure user/group names and unit files remain portable among Linux systems.

When used in conjunction with DynamicUser= the user/group name specified is dynamically allocated at the time the service is started, and released at the time the service is stopped --- unless it is already allocated statically (see below). If DynamicUser= is not used the specified user and group must have been created statically in the user database no later than the moment the service is started, for example using the sysusers.d(5) facility, which is applied at boot or package install time.

DynamicUser=

Takes a boolean parameter. If set, a UNIX user and group pair is allocated dynamically when the unit is started, and released as soon as it is stopped. The user and group will not be added to /etc/passwd or /etc/group, but are managed transiently during runtime. The nss-systemd(8) glibc NSS module provides integration of these dynamic users/groups into the system's user and group databases. The user and group name to use may be configured via User= and Group= (see above). If these options are not used and dynamic user/group allocation is enabled for a unit, the name of the dynamic user/group is implicitly derived from the unit name. If the unit name without the type suffix qualifies as valid user name it is used directly, otherwise a name incorporating a hash of it is used. If a statically allocated user or group of the configured name already exists, it is used and no dynamic user/group is allocated. Note that if User= is specified and the static group with the name exists, then it is required that the static user with the name already exists. Similarly, if Group= is specified and the static user with the name exists, then it is required that the static group with the name already exists. Dynamic users/groups are allocated from the UID/GID range 61184...65519. It is recommended to avoid this range for regular system or login users. At any point in time each UID/GID from this range is only assigned to zero or one dynamically allocated users/groups in use. However, UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to these files or directories. If DynamicUser= is enabled, RemoveIPC=, PrivateTmp= are implied. This ensures that the lifetime of IPC objects and temporary files created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic user/group. Since /tmp and /var/tmp are usually the only world-writable directories on a system this ensures that a unit making use of dynamic user/group allocation cannot leave files around after unit termination. Furthermore NoNewPrivileges= and RestrictSUIDSGID= are implicitly enabled to ensure that processes invoked cannot take benefit or create SUID/SGID files or directories. Moreover ProtectSystem=strict and ProtectHome=read-only are implied, thus prohibiting the service to write to arbitrary file system locations. In order to allow the service to write to certain directories, they have to be whitelisted using ReadWritePaths=, but care must be taken so that UID/GID recycling doesn't create security issues involving files created by the service. Use RuntimeDirectory= (see below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and removed automatically when the unit is terminated. Use StateDirectory=, CacheDirectory= and LogsDirectory= in order to assign a set of writable directories for specific purposes to the service in a way that they are protected from vulnerabilities due to UID reuse (see below). Defaults to off.

SupplementaryGroups=

Sets the supplementary Unix groups the processes are executed as. This takes a space-separated list of group names or IDs. This option may be specified more than once, in which case all listed groups are set as supplementary groups. When the empty string is assigned, the list of supplementary groups is reset, and all assignments prior to this one will have no effect. In any way, this option does not override, but extends the list of supplementary groups configured in the system group database for the user. This does not affect commands prefixed with "+".

PAMName=

Sets the PAM service name to set up a session as. If set, the executed process will be registered as a PAM session under the specified service name. This is only useful in conjunction with the User= setting, and is otherwise ignored. If not set, no PAM session will be opened for the executed processes. See pam(8) for details.

Note that for each unit making use of this option a PAM session handler process will be maintained as part of the unit and stays around as long as the unit is active, to ensure that appropriate actions can be taken when the unit and hence the PAM session terminates. This process is named "(sd-pam)" and is an immediate child process of the unit's main process.

Note that when this option is used for a unit it is very likely (depending on PAM configuration) that the main unit process will be migrated to its own session scope unit when it is activated. This process will hence be associated with two units: the unit it was originally started from (and for which PAMName= was configured), and the session scope unit. Any child processes of that process will however be associated with the session scope unit only. This has implications when used in combination with NotifyAccess=all, as these child processes will not be able to affect changes in the original unit through notification messages. These messages will be considered belonging to the session scope unit and not the original unit. It is hence not recommended to use PAMName= in combination with NotifyAccess=all.

 

CAPABILITIES

CapabilityBoundingSet=

Controls which capabilities to include in the capability bounding set for the executed process. See capabilities(7) for details. Takes a whitespace-separated list of capability names, e.g. CAP_SYS_ADMIN, CAP_DAC_OVERRIDE, CAP_SYS_PTRACE. Capabilities listed will be included in the bounding set, all others are removed. If the list of capabilities is prefixed with "~", all but the listed capabilities will be included, the effect of the assignment inverted. Note that this option also affects the respective capabilities in the effective, permitted and inheritable capability sets. If this option is not used, the capability bounding set is not modified on process execution, hence no limits on the capabilities of the process are enforced. This option may appear more than once, in which case the bounding sets are merged by AND, or by OR if the lines are prefixed with "~" (see below). If the empty string is assigned to this option, the bounding set is reset to the empty capability set, and all prior settings have no effect. If set to "~" (without any further argument), the bounding set is reset to the full set of available capabilities, also undoing any previous settings. This does not affect commands prefixed with "+".

Example: if a unit has the following,

CapabilityBoundingSet=CAP_A CAP_B
CapabilityBoundingSet=CAP_B CAP_C

then CAP_A, CAP_B, and CAP_C are set. If the second line is prefixed with "~", e.g.,

CapabilityBoundingSet=CAP_A CAP_B
CapabilityBoundingSet=~CAP_B CAP_C

then, only CAP_A is set.

AmbientCapabilities=

Controls which capabilities to include in the ambient capability set for the executed process. Takes a whitespace-separated list of capability names, e.g. CAP_SYS_ADMIN, CAP_DAC_OVERRIDE, CAP_SYS_PTRACE. This option may appear more than once in which case the ambient capability sets are merged (see the above examples in CapabilityBoundingSet=). If the list of capabilities is prefixed with "~", all but the listed capabilities will be included, the effect of the assignment inverted. If the empty string is assigned to this option, the ambient capability set is reset to the empty capability set, and all prior settings have no effect. If set to "~" (without any further argument), the ambient capability set is reset to the full set of available capabilities, also undoing any previous settings. Note that adding capabilities to ambient capability set adds them to the process's inherited capability set.

Ambient capability sets are useful if you want to execute a process as a non-privileged user but still want to give it some capabilities. Note that in this case option keep-caps is automatically added to SecureBits= to retain the capabilities over the user change. AmbientCapabilities= does not affect commands prefixed with "+".

 

SECURITY

NoNewPrivileges=

Takes a boolean argument. If true, ensures that the service process and all its children can never gain new privileges through execve() (e.g. via setuid or setgid bits, or filesystem capabilities). This is the simplest and most effective way to ensure that a process and its children can never elevate privileges again. Defaults to false, but certain settings override this and ignore the value of this setting. This is the case when SystemCallFilter=, SystemCallArchitectures=, RestrictAddressFamilies=, RestrictNamespaces=, PrivateDevices=, ProtectKernelTunables=, ProtectKernelModules=, MemoryDenyWriteExecute=, RestrictRealtime=, RestrictSUIDSGID=, DynamicUser= or LockPersonality= are specified. Note that even if this setting is overridden by them, systemctl show shows the original value of this setting. Also see m[blue]No New Privileges Flagm[][2].

SecureBits=

Controls the secure bits set for the executed process. Takes a space-separated combination of options from the following list: keep-caps, keep-caps-locked, no-setuid-fixup, no-setuid-fixup-locked, noroot, and noroot-locked. This option may appear more than once, in which case the secure bits are ORed. If the empty string is assigned to this option, the bits are reset to 0. This does not affect commands prefixed with "+". See capabilities(7) for details.
 

MANDATORY ACCESS CONTROL

SELinuxContext=

Set the SELinux security context of the executed process. If set, this will override the automated domain transition. However, the policy still needs to authorize the transition. This directive is ignored if SELinux is disabled. If prefixed by "-", all errors will be ignored. This does not affect commands prefixed with "+". See setexeccon(3) for details.

AppArmorProfile=

Takes a profile name as argument. The process executed by the unit will switch to this profile when started. Profiles must already be loaded in the kernel, or the unit will fail. This result in a non operation if AppArmor is not enabled. If prefixed by "-", all errors will be ignored. This does not affect commands prefixed with "+".

SmackProcessLabel=

Takes a SMACK64 security label as argument. The process executed by the unit will be started under this label and SMACK will decide whether the process is allowed to run or not, based on it. The process will continue to run under the label specified here unless the executable has its own SMACK64EXEC label, in which case the process will transition to run under that label. When not specified, the label that systemd is running under is used. This directive is ignored if SMACK is disabled.

The value may be prefixed by "-", in which case all errors will be ignored. An empty value may be specified to unset previous assignments. This does not affect commands prefixed with "+".

 

PROCESS PROPERTIES

LimitCPU=, LimitFSIZE=, LimitDATA=, LimitSTACK=, LimitCORE=, LimitRSS=, LimitNOFILE=, LimitAS=, LimitNPROC=, LimitMEMLOCK=, LimitLOCKS=, LimitSIGPENDING=, LimitMSGQUEUE=, LimitNICE=, LimitRTPRIO=, LimitRTTIME=

Set soft and hard limits on various resources for executed processes. See setrlimit(2) for details on the resource limit concept. Resource limits may be specified in two formats: either as single value to set a specific soft and hard limit to the same value, or as colon-separated pair soft:hard to set both limits individually (e.g. "LimitAS=4G:16G"). Use the string infinity to configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base 1024) may be used for resource limits measured in bytes (e.g. LimitAS=16G). For the limits referring to time values, the usual time units ms, s, min, h and so on may be used (see systemd.time(7) for details). Note that if no time unit is specified for LimitCPU= the default unit of seconds is implied, while for LimitRTTIME= the default unit of microseconds is implied. Also, note that the effective granularity of the limits might influence their enforcement. For example, time limits specified for LimitCPU= will be rounded up implicitly to multiples of 1s. For LimitNICE= the value may be specified in two syntaxes: if prefixed with "+" or "-", the value is understood as regular Linux nice value in the range -20..19. If not prefixed like this the value is understood as raw resource limit parameter in the range 0..40 (with 0 being equivalent to 1).

Note that most process resource limits configured with these options are per-process, and processes may fork in order to acquire a new set of resources that are accounted independently of the original process, and may thus escape limits set. Also note that LimitRSS= is not implemented on Linux, and setting it has no effect. Often it is advisable to prefer the resource controls listed in systemd.resource-control(5) over these per-process limits, as they apply to services as a whole, may be altered dynamically at runtime, and are generally more expressive. For example, MemoryLimit= is a more powerful (and working) replacement for LimitRSS=.

For system units these resource limits may be chosen freely. For user units however (i.e. units run by a per-user instance of systemd(1)), these limits are bound by (possibly more restrictive) per-user limits enforced by the OS.

Resource limits not configured explicitly for a unit default to the value configured in the various DefaultLimitCPU=, DefaultLimitFSIZE=, ... options available in systemd-system.conf(5), and - if not configured there - the kernel or per-user defaults, as defined by the OS (the latter only for user services, see above).


Table 1. Resource limit directives, their equivalent ulimit shell commands and the unit used

Directive ulimit equivalent Unit
LimitCPU= ulimit -t Seconds
LimitFSIZE= ulimit -f Bytes
LimitDATA= ulimit -d Bytes
LimitSTACK= ulimit -s Bytes
LimitCORE= ulimit -c Bytes
LimitRSS= ulimit -m Bytes
LimitNOFILE= ulimit -n Number of File Descriptors
LimitAS= ulimit -v Bytes
LimitNPROC= ulimit -u Number of Processes
LimitMEMLOCK= ulimit -l Bytes
LimitLOCKS= ulimit -x Number of Locks
LimitSIGPENDING= ulimit -i Number of Queued Signals
LimitMSGQUEUE= ulimit -q Bytes
LimitNICE= ulimit -e Nice Level
LimitRTPRIO= ulimit -r Realtime Priority
LimitRTTIME= No equivalent Microseconds

UMask=

Controls the file mode creation mask. Takes an access mode in octal notation. See umask(2) for details. Defaults to 0022 for system units. For units of the user service manager the default value is inherited from the user instance (whose default is inherited from the system service manager, and thus also is 0022). Hence changing the default value of a user instance, either via UMask= or via a PAM module, will affect the user instance itself and all user units started by the user instance unless a user unit has specified its own UMask=.

KeyringMode=

Controls how the kernel session keyring is set up for the service (see session-keyring(7) for details on the session keyring). Takes one of inherit, private, shared. If set to inherit no special keyring setup is done, and the kernel's default behaviour is applied. If private is used a new session keyring is allocated when a service process is invoked, and it is not linked up with any user keyring. This is the recommended setting for system services, as this ensures that multiple services running under the same system user ID (in particular the root user) do not share their key material among each other. If shared is used a new session keyring is allocated as for private, but the user keyring of the user configured with User= is linked into it, so that keys assigned to the user may be requested by the unit's processes. In this modes multiple units running processes under the same user ID may share key material. Unless inherit is selected the unique invocation ID for the unit (see below) is added as a protected key by the name "invocation_id" to the newly created session keyring. Defaults to private for the system service manager and to inherit for the user service manager.

OOMScoreAdjust=

Sets the adjustment level for the Out-Of-Memory killer for executed processes. Takes an integer between -1000 (to disable OOM killing for this process) and 1000 (to make killing of this process under memory pressure very likely). See m[blue]proc.txtm[][3] for details.

TimerSlackNSec=

Sets the timer slack in nanoseconds for the executed processes. The timer slack controls the accuracy of wake-ups triggered by timers. See prctl(2) for more information. Note that in contrast to most other time span definitions this parameter takes an integer value in nano-seconds if no unit is specified. The usual time units are understood too.

Personality=

Controls which kernel architecture uname(2) shall report, when invoked by unit processes. Takes one of the architecture identifiers x86, x86-64, ppc, ppc-le, ppc64, ppc64-le, s390 or s390x. Which personality architectures are supported depends on the system architecture. Usually the 64bit versions of the various system architectures support their immediate 32bit personality architecture counterpart, but no others. For example, x86-64 systems support the x86-64 and x86 personalities but no others. The personality feature is useful when running 32-bit services on a 64-bit host system. If not specified, the personality is left unmodified and thus reflects the personality of the host system's kernel.

IgnoreSIGPIPE=

Takes a boolean argument. If true, causes SIGPIPE to be ignored in the executed process. Defaults to true because SIGPIPE generally is useful only in shell pipelines.
 

SCHEDULING

Nice=

Sets the default nice level (scheduling priority) for executed processes. Takes an integer between -20 (highest priority) and 19 (lowest priority). See setpriority(2) for details.

CPUSchedulingPolicy=

Sets the CPU scheduling policy for executed processes. Takes one of other, batch, idle, fifo or rr. See sched_setscheduler(2) for details.

CPUSchedulingPriority=

Sets the CPU scheduling priority for executed processes. The available priority range depends on the selected CPU scheduling policy (see above). For real-time scheduling policies an integer between 1 (lowest priority) and 99 (highest priority) can be used. See sched_setscheduler(2) for details.

CPUSchedulingResetOnFork=

Takes a boolean argument. If true, elevated CPU scheduling priorities and policies will be reset when the executed processes fork, and can hence not leak into child processes. See sched_setscheduler(2) for details. Defaults to false.

CPUAffinity=

Controls the CPU affinity of the executed processes. Takes a list of CPU indices or ranges separated by either whitespace or commas. CPU ranges are specified by the lower and upper CPU indices separated by a dash. This option may be specified more than once, in which case the specified CPU affinity masks are merged. If the empty string is assigned, the mask is reset, all assignments prior to this will have no effect. See sched_setaffinity(2) for details.

IOSchedulingClass=

Sets the I/O scheduling class for executed processes. Takes an integer between 0 and 3 or one of the strings none, realtime, best-effort or idle. See ioprio_set(2) for details.

IOSchedulingPriority=

Sets the I/O scheduling priority for executed processes. Takes an integer between 0 (highest priority) and 7 (lowest priority). The available priorities depend on the selected I/O scheduling class (see above). See ioprio_set(2) for details.
 

SANDBOXING

ProtectSystem=

Takes a boolean argument or the special values "full" or "strict". If true, mounts the /usr and /boot directories read-only for processes invoked by this unit. If set to "full", the /etc directory is mounted read-only, too. If set to "strict" the entire file system hierarchy is mounted read-only, except for the API file system subtrees /dev, /proc and /sys (protect these directories using PrivateDevices=, ProtectKernelTunables=, ProtectControlGroups=). This setting ensures that any modification of the vendor-supplied operating system (and optionally its configuration, and local mounts) is prohibited for the service. It is recommended to enable this setting for all long-running services, unless they are involved with system updates or need to modify the operating system in other ways. If this option is used, ReadWritePaths= may be used to exclude specific directories from being made read-only. This setting is implied if DynamicUser= is set. For this setting the same restrictions regarding mount propagation and privileges apply as for ReadOnlyPaths= and related calls, see below. Defaults to off.

ProtectHome=

Takes a boolean argument or "read-only". If true, the directories /home, /root and /run/user are made inaccessible and empty for processes invoked by this unit. If set to "read-only", the three directories are made read-only instead. It is recommended to enable this setting for all long-running services (in particular network-facing ones), to ensure they cannot get access to private user data, unless the services actually require access to the user's private data. This setting is implied if DynamicUser= is set. For this setting the same restrictions regarding mount propagation and privileges apply as for ReadOnlyPaths= and related calls, see below.

RuntimeDirectory=, StateDirectory=, CacheDirectory=, LogsDirectory=, ConfigurationDirectory=

These options take a whitespace-separated list of directory names. The specified directory names must be relative, and may not include "." or "..". If set, one or more directories by the specified names will be created (including their parents) below /run (or $XDG_RUNTIME_DIR for user services), /var/lib (or $XDG_CONFIG_HOME for user services), /var/cache (or $XDG_CACHE_HOME for user services), /var/log (or $XDG_CONFIG_HOME/log for user services), or /etc (or $XDG_CONFIG_HOME for user services), respectively, when the unit is started.

In case of RuntimeDirectory= the lowest subdirectories are removed when the unit is stopped. It is possible to preserve the specified directories in this case if RuntimeDirectoryPreserve= is configured to restart or yes (see below). The directories specified with StateDirectory=, CacheDirectory=, LogsDirectory=, ConfigurationDirectory= are not removed when the unit is stopped.

Except in case of ConfigurationDirectory=, the innermost specified directories will be owned by the user and group specified in User= and Group=. If the specified directories already exist and their owning user or group do not match the configured ones, all files and directories below the specified directories as well as the directories themselves will have their file ownership recursively changed to match what is configured. As an optimization, if the specified directories are already owned by the right user and group, files and directories below of them are left as-is, even if they do not match what is requested. The innermost specified directories will have their access mode adjusted to the what is specified in RuntimeDirectoryMode=, StateDirectoryMode=, CacheDirectoryMode=, LogsDirectoryMode= and ConfigurationDirectoryMode=.

These options imply BindPaths= for the specified paths. When combined with RootDirectory= or RootImage= these paths always reside on the host and are mounted from there into the unit's file system namespace.

If DynamicUser= is used in conjunction with StateDirectory=, CacheDirectory= and LogsDirectory= is slightly altered: the directories are created below /var/lib/private, /var/cache/private and /var/log/private, respectively, which are host directories made inaccessible to unprivileged users, which ensures that access to these directories cannot be gained through dynamic user ID recycling. Symbolic links are created to hide this difference in behaviour. Both from perspective of the host and from inside the unit, the relevant directories hence always appear directly below /var/lib, /var/cache and /var/log.

Use RuntimeDirectory= to manage one or more runtime directories for the unit and bind their lifetime to the daemon runtime. This is particularly useful for unprivileged daemons that cannot create runtime directories in /run due to lack of privileges, and to make sure the runtime directory is cleaned up automatically after use. For runtime directories that require more complex or different configuration or lifetime guarantees, please consider using tmpfiles.d(5).

Example: if a system service unit has the following,

RuntimeDirectory=foo/bar baz

the service manager creates /run/foo (if it does not exist), /run/foo/bar, and /run/baz. The directories /run/foo/bar and /run/baz except /run/foo are owned by the user and group specified in User= and Group=, and removed when the service is stopped.

RuntimeDirectoryMode=, StateDirectoryMode=, CacheDirectoryMode=, LogsDirectoryMode=, ConfigurationDirectoryMode=

Specifies the access mode of the directories specified in RuntimeDirectory=, StateDirectory=, CacheDirectory=, LogsDirectory=, or ConfigurationDirectory=, respectively, as an octal number. Defaults to 0755. See "Permissions" in path_resolution(7) for a discussion of the meaning of permission bits.

RuntimeDirectoryPreserve=

Takes a boolean argument or restart. If set to no (the default), the directories specified in RuntimeDirectory= are always removed when the service stops. If set to restart the directories are preserved when the service is both automatically and manually restarted. Here, the automatic restart means the operation specified in Restart=, and manual restart means the one triggered by systemctl restart foo.service. If set to yes, then the directories are not removed when the service is stopped. Note that since the runtime directory /run is a mount point of "tmpfs", then for system services the directories specified in RuntimeDirectory= are removed when the system is rebooted.

ReadWritePaths=, ReadOnlyPaths=, InaccessiblePaths=

Sets up a new file system namespace for executed processes. These options may be used to limit access a process might have to the file system hierarchy. Each setting takes a space-separated list of paths relative to the host's root directory (i.e. the system running the service manager). Note that if paths contain symlinks, they are resolved relative to the root directory set with RootDirectory=/RootImage=.

Paths listed in ReadWritePaths= are accessible from within the namespace with the same access modes as from outside of it. Paths listed in ReadOnlyPaths= are accessible for reading only, writing will be refused even if the usual file access controls would permit this. Nest ReadWritePaths= inside of ReadOnlyPaths= in order to provide writable subdirectories within read-only directories. Use ReadWritePaths= in order to whitelist specific paths for write access if ProtectSystem=strict is used. Paths listed in InaccessiblePaths= will be made inaccessible for processes inside the namespace (along with everything below them in the file system hierarchy).

Note that restricting access with these options does not extend to submounts of a directory that are created later on. Non-directory paths may be specified as well. These options may be specified more than once, in which case all paths listed will have limited access from within the namespace. If the empty string is assigned to this option, the specific list is reset, and all prior assignments have no effect.

Paths in ReadWritePaths=, ReadOnlyPaths= and InaccessiblePaths= may be prefixed with "-", in which case they will be ignored when they do not exist. If prefixed with "+" the paths are taken relative to the root directory of the unit, as configured with RootDirectory=/RootImage=, instead of relative to the root directory of the host (see above). When combining "-" and "+" on the same path make sure to specify "-" first, and "+" second.

Note that using this setting will disconnect propagation of mounts from the service to the host (propagation in the opposite direction continues to work). This means that this setting may not be used for services which shall be able to install mount points in the main mount namespace. Note that the effect of these settings may be undone by privileged processes. In order to set up an effective sandboxed environment for a unit it is thus recommended to combine these settings with either CapabilityBoundingSet=~CAP_SYS_ADMIN or SystemCallFilter=~@mount.

PrivateTmp=

Takes a boolean argument. If true, sets up a new file system namespace for the executed processes and mounts private /tmp and /var/tmp directories inside it that is not shared by processes outside of the namespace. This is useful to secure access to temporary files of the process, but makes sharing between processes via /tmp or /var/tmp impossible. If this is enabled, all temporary files created by a service in these directories will be removed after the service is stopped. Defaults to false. It is possible to run two or more units within the same private /tmp and /var/tmp namespace by using the JoinsNamespaceOf= directive, see systemd.unit(5) for details. This setting is implied if DynamicUser= is set. For this setting the same restrictions regarding mount propagation and privileges apply as for ReadOnlyPaths= and related calls, see above. Enabling this setting has the side effect of adding Requires= and After= dependencies on all mount units necessary to access /tmp and /var/tmp. Moreover an implicitly After= ordering on systemd-tmpfiles-setup.service(8) is added.

Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security.

PrivateDevices=

Takes a boolean argument. If true, sets up a new /dev mount for the executed processes and only adds API pseudo devices such as /dev/null, /dev/zero or /dev/random (as well as the pseudo TTY subsystem) to it, but no physical devices such as /dev/sda, system memory /dev/mem, system ports /dev/port and others. This is useful to securely turn off physical device access by the executed process. Defaults to false. Enabling this option will install a system call filter to block low-level I/O system calls that are grouped in the @raw-io set, will also remove CAP_MKNOD and CAP_SYS_RAWIO from the capability bounding set for the unit (see above), and set DevicePolicy=closed (see systemd.resource-control(5) for details). Note that using this setting will disconnect propagation of mounts from the service to the host (propagation in the opposite direction continues to work). This means that this setting may not be used for services which shall be able to install mount points in the main mount namespace. The new /dev will be mounted read-only and 'noexec'. The latter may break old programs which try to set up executable memory by using mmap(2) of /dev/zero instead of using MAP_ANON. For this setting the same restrictions regarding mount propagation and privileges apply as for ReadOnlyPaths= and related calls, see above. If turned on and if running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=), NoNewPrivileges=yes is implied.

Note that the implementation of this setting might be impossible (for example if mount namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security.

PrivateNetwork=

Takes a boolean argument. If true, sets up a new network namespace for the executed processes and configures only the loopback network device "lo" inside it. No other network devices will be available to the executed process. This is useful to turn off network access by the executed process. Defaults to false. It is possible to run two or more units within the same private network namespace by using the JoinsNamespaceOf= directive, see systemd.unit(5) for details. Note that this option will disconnect all socket families from the host, this includes AF_NETLINK and AF_UNIX. The latter has the effect that AF_UNIX sockets in the abstract socket namespace will become unavailable to the processes (however, those located in the file system will continue to be accessible).

Note that the implementation of this setting might be impossible (for example if network namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security.

PrivateUsers=

Takes a boolean argument. If true, sets up a new user namespace for the executed processes and configures a minimal user and group mapping, that maps the "root" user and group as well as the unit's own user and group to themselves and everything else to the "nobody" user and group. This is useful to securely detach the user and group databases used by the unit from the rest of the system, and thus to create an effective sandbox environment. All files, directories, processes, IPC objects and other resources owned by users/groups not equaling "root" or the unit's own will stay visible from within the unit but appear owned by the "nobody" user and group. If this mode is enabled, all unit processes are run without privileges in the host user namespace (regardless if the unit's own user/group is "root" or not). Specifically this means that the process will have zero process capabilities on the host's user namespace, but full capabilities within the service's user namespace. Settings such as CapabilityBoundingSet= will affect only the latter, and there's no way to acquire additional capabilities in the host's user namespace. Defaults to off.

This setting is particularly useful in conjunction with RootDirectory=/RootImage=, as the need to synchronize the user and group databases in the root directory and on the host is reduced, as the only users and groups who need to be matched are "root", "nobody" and the unit's own user and group.

Note that the implementation of this setting might be impossible (for example if user namespaces are not available), and the unit should be written in a way that does not solely rely on this setting for security.

ProtectKernelTunables=

Takes a boolean argument. If true, kernel variables accessible through /proc/sys, /sys, /proc/sysrq-trigger, /proc/latency_stats, /proc/acpi, /proc/timer_stats, /proc/fs and /proc/irq will be made read-only to all processes of the unit. Usually, tunable kernel variables should be initialized only at boot-time, for example with the sysctl.d(5) mechanism. Few services need to write to these at runtime; it is hence recommended to turn this on for most services. For this setting the same restrictions regarding mount propagation and privileges apply as for ReadOnlyPaths= and related calls, see above. Defaults to off. If turned on and if running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. services for which User= is set), NoNewPrivileges=yes is implied. Note that this option does not prevent indirect changes to kernel tunables effected by IPC calls to other processes. However, InaccessiblePaths= may be used to make relevant IPC file system objects inaccessible. If ProtectKernelTunables= is set, MountAPIVFS=yes is implied.

ProtectKernelModules=

Takes a boolean argument. If true, explicit module loading will be denied. This allows to turn off module load and unload operations on modular kernels. It is recommended to turn this on for most services that do not need special file systems or extra kernel modules to work. Defaults to off. Enabling this option removes CAP_SYS_MODULE from the capability bounding set for the unit, and installs a system call filter to block module system calls, also /usr/lib/modules is made inaccessible. For this setting the same restrictions regarding mount propagation and privileges apply as for ReadOnlyPaths= and related calls, see above. Note that limited automatic module loading due to user configuration or kernel mapping tables might still happen as side effect of requested user operations, both privileged and unprivileged. To disable module auto-load feature please see sysctl.d(5) kernel.modules_disabled mechanism and /proc/sys/kernel/modules_disabled documentation. If turned on and if running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=), NoNewPrivileges=yes is implied.

ProtectControlGroups=

Takes a boolean argument. If true, the Linux Control Groups (cgroups(7)) hierarchies accessible through /sys/fs/cgroup will be made read-only to all processes of the unit. Except for container managers no services should require write access to the control groups hierarchies; it is hence recommended to turn this on for most services. For this setting the same restrictions regarding mount propagation and privileges apply as for ReadOnlyPaths= and related calls, see above. Defaults to off. If ProtectControlGroups= is set, MountAPIVFS=yes is implied.

RestrictAddressFamilies=

Restricts the set of socket address families accessible to the processes of this unit. Takes a space-separated list of address family names to whitelist, such as AF_UNIX, AF_INET or AF_INET6. When prefixed with ~ the listed address families will be applied as blacklist, otherwise as whitelist. Note that this restricts access to the socket(2) system call only. Sockets passed into the process by other means (for example, by using socket activation with socket units, see systemd.socket(5)) are unaffected. Also, sockets created with socketpair() (which creates connected AF_UNIX sockets only) are unaffected. Note that this option has no effect on 32-bit x86, s390, s390x, mips, mips-le, ppc, ppc-le, pcc64, ppc64-le and is ignored (but works correctly on other ABIs, including x86-64). Note that on systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option. Specifically, it is recommended to combine this option with SystemCallArchitectures=native or similar. If running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=nobody), NoNewPrivileges=yes is implied. By default, no restrictions apply, all address families are accessible to processes. If assigned the empty string, any previous address familiy restriction changes are undone. This setting does not affect commands prefixed with "+".

Use this option to limit exposure of processes to remote access, in particular via exotic and sensitive network protocols, such as AF_PACKET. Note that in most cases, the local AF_UNIX address family should be included in the configured whitelist as it is frequently used for local communication, including for syslog(2) logging.

RestrictNamespaces=

Restricts access to Linux namespace functionality for the processes of this unit. For details about Linux namespaces, see namespaces(7). Either takes a boolean argument, or a space-separated list of namespace type identifiers. If false (the default), no restrictions on namespace creation and switching are made. If true, access to any kind of namespacing is prohibited. Otherwise, a space-separated list of namespace type identifiers must be specified, consisting of any combination of: cgroup, ipc, net, mnt, pid, user and uts. Any namespace type listed is made accessible to the unit's processes, access to namespace types not listed is prohibited (whitelisting). By prepending the list with a single tilde character ("~") the effect may be inverted: only the listed namespace types will be made inaccessible, all unlisted ones are permitted (blacklisting). If the empty string is assigned, the default namespace restrictions are applied, which is equivalent to false. Internally, this setting limits access to the unshare(2), clone(2) and setns(2) system calls, taking the specified flags parameters into account. Note that --- if this option is used --- in addition to restricting creation and switching of the specified types of namespaces (or all of them, if true) access to the setns() system call with a zero flags parameter is prohibited. This setting is only supported on x86, x86-64, mips, mips-le, mips64, mips64-le, mips64-n32, mips64-le-n32, ppc64, ppc64-le, s390 and s390x, and enforces no restrictions on other architectures. If running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=), NoNewPrivileges=yes is implied.

LockPersonality=

Takes a boolean argument. If set, locks down the personality(2) system call so that the kernel execution domain may not be changed from the default or the personality selected with Personality= directive. This may be useful to improve security, because odd personality emulations may be poorly tested and source of vulnerabilities. If running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=), NoNewPrivileges=yes is implied.

MemoryDenyWriteExecute=

Takes a boolean argument. If set, attempts to create memory mappings that are writable and executable at the same time, or to change existing memory mappings to become executable, or mapping shared memory segments as executable are prohibited. Specifically, a system call filter is added that rejects mmap(2) system calls with both PROT_EXEC and PROT_WRITE set, mprotect(2) or pkey_mprotect(2) system calls with PROT_EXEC set and shmat(2) system calls with SHM_EXEC set. Note that this option is incompatible with programs and libraries that generate program code dynamically at runtime, including JIT execution engines, executable stacks, and code "trampoline" feature of various C compilers. This option improves service security, as it makes harder for software exploits to change running code dynamically. Note that this feature is fully available on x86-64, and partially on x86. Specifically, the shmat() protection is not available on x86. Note that on systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option. Specifically, it is recommended to combine this option with SystemCallArchitectures=native or similar. If running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=), NoNewPrivileges=yes is implied.

RestrictRealtime=

Takes a boolean argument. If set, any attempts to enable realtime scheduling in a process of the unit are refused. This restricts access to realtime task scheduling policies such as SCHED_FIFO, SCHED_RR or SCHED_DEADLINE. See sched(7) for details about these scheduling policies. If running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=), NoNewPrivileges=yes is implied. Realtime scheduling policies may be used to monopolize CPU time for longer periods of time, and may hence be used to lock up or otherwise trigger Denial-of-Service situations on the system. It is hence recommended to restrict access to realtime scheduling to the few programs that actually require them. Defaults to off.

RestrictSUIDSGID=

Takes a boolean argument. If set, any attempts to set the set-user-ID (SUID) or set-group-ID (SGID) bits on files or directories will be denied (for details on these bits see inode(7)). If running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=), NoNewPrivileges=yes is implied. As the SUID/SGID bits are mechanisms to elevate privileges, and allows users to acquire the identity of other users, it is recommended to restrict creation of SUID/SGID files to the few programs that actually require them. Note that this restricts marking of any type of file system object with these bits, including both regular files and directories (where the SGID is a different meaning than for files, see documentation). This option is implied if DynamicUser= is enabled. Defaults to off.

RemoveIPC=

Takes a boolean parameter. If set, all System V and POSIX IPC objects owned by the user and group the processes of this unit are run as are removed when the unit is stopped. This setting only has an effect if at least one of User=, Group= and DynamicUser= are used. It has no effect on IPC objects owned by the root user. Specifically, this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If multiple units use the same user or group the IPC objects are removed when the last of these units is stopped. This setting is implied if DynamicUser= is set.

MountFlags=

Takes a mount propagation flag: shared, slave or private, which control whether mounts in the file system namespace set up for this unit's processes will receive or propagate mounts and unmounts. See mount(2) for details. Defaults to shared. Use shared to ensure that mounts and unmounts are propagated from systemd's namespace to the service's namespace and vice versa. Use slave to run processes so that none of their mounts and unmounts will propagate to the host. Use private to also ensure that no mounts and unmounts from the host will propagate into the unit processes' namespace. If this is set to slave or private, any mounts created by spawned processes will be unmounted after the completion of the current command line of ExecStartPre=, ExecStartPost=, ExecStart=, and ExecStopPost=. Note that slave means that file systems mounted on the host might stay mounted continuously in the unit's namespace, and thus keep the device busy. Note that the file system namespace related options (PrivateTmp=, PrivateDevices=, ProtectSystem=, ProtectHome=, ProtectKernelTunables=, ProtectControlGroups=, ReadOnlyPaths=, InaccessiblePaths=, ReadWritePaths=) require that mount and unmount propagation from the unit's file system namespace is disabled, and hence downgrade shared to slave.
 

SYSTEM CALL FILTERING

SystemCallFilter=

Takes a space-separated list of system call names. If this setting is used, all system calls executed by the unit processes except for the listed ones will result in immediate process termination with the SIGSYS signal (whitelisting). If the first character of the list is "~", the effect is inverted: only the listed system calls will result in immediate process termination (blacklisting). Blacklisted system calls and system call groups may optionally be suffixed with a colon (":") and "errno" error number (between 0 and 4095) or errno name such as EPERM, EACCES or EUCLEAN. This value will be returned when a blacklisted system call is triggered, instead of terminating the processes immediately. This value takes precedence over the one given in SystemCallErrorNumber=. If running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=nobody), NoNewPrivileges=yes is implied. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') and is useful for enforcing a minimal sandboxing environment. Note that the execve, exit, exit_group, getrlimit, rt_sigreturn, sigreturn system calls and the system calls for querying time and sleeping are implicitly whitelisted and do not need to be listed explicitly. This option may be specified more than once, in which case the filter masks are merged. If the empty string is assigned, the filter is reset, all prior assignments will have no effect. This does not affect commands prefixed with "+".

Note that on systems supporting multiple ABIs (such as x86/x86-64) it is recommended to turn off alternative ABIs for services, so that they cannot be used to circumvent the restrictions of this option. Specifically, it is recommended to combine this option with SystemCallArchitectures=native or similar.

Note that strict system call filters may impact execution and error handling code paths of the service invocation. Specifically, access to the execve system call is required for the execution of the service binary --- if it is blocked service invocation will necessarily fail. Also, if execution of the service binary fails for some reason (for example: missing service executable), the error handling logic might require access to an additional set of system calls in order to process and log this failure correctly. It might be necessary to temporarily disable system call filters in order to simplify debugging of such failures.

If you specify both types of this option (i.e. whitelisting and blacklisting), the first encountered will take precedence and will dictate the default action (termination or approval of a system call). Then the next occurrences of this option will add or delete the listed system calls from the set of the filtered system calls, depending of its type and the default action. (For example, if you have started with a whitelisting of read and write, and right after it add a blacklisting of write, then write will be removed from the set.)

As the number of possible system calls is large, predefined sets of system calls are provided. A set starts with "@" character, followed by name of the set.


Table 2. Currently predefined system call sets

Set Description
@aio Asynchronous I/O (io_setup(2), io_submit(2), and related calls)
@basic-io System calls for basic I/O: reading, writing, seeking, file descriptor duplication and closing (read(2), write(2), and related calls)
@chown Changing file ownership (chown(2), fchownat(2), and related calls)
@clock System calls for changing the system clock (adjtimex(2), settimeofday(2), and related calls)
@cpu-emulation System calls for CPU emulation functionality (vm86(2) and related calls)
@debug Debugging, performance monitoring and tracing functionality (ptrace(2), perf_event_open(2) and related calls)
@file-system File system operations: opening, creating files and directories for read and write, renaming and removing them, reading file properties, or creating hard and symbolic links.
@io-event Event loop system calls (poll(2), select(2), epoll(7), eventfd(2) and related calls)
@ipc Pipes, SysV IPC, POSIX Message Queues and other IPC (mq_overview(7), svipc(7))
@keyring Kernel keyring access (keyctl(2) and related calls)
@memlock Locking of memory into RAM (mlock(2), mlockall(2) and related calls)
@module Loading and unloading of kernel modules (init_module(2), delete_module(2) and related calls)
@mount Mounting and unmounting of file systems (mount(2), chroot(2), and related calls)
@network-io Socket I/O (including local AF_UNIX): socket(7), unix(7)
@obsolete Unusual, obsolete or unimplemented (create_module(2), gtty(2), ...)
@privileged All system calls which need super-user capabilities (capabilities(7))
@process Process control, execution, namespaceing operations (clone(2), kill(2), namespaces(7), ...
@raw-io Raw I/O port access (ioperm(2), iopl(2), pciconfig_read(), ...)
@reboot System calls for rebooting and reboot preparation (reboot(2), kexec(), ...)
@resources System calls for changing resource limits, memory and scheduling parameters (setrlimit(2), setpriority(2), ...)
@setuid System calls for changing user ID and group ID credentials, (setuid(2), setgid(2), setresuid(2), ...)
@signal System calls for manipulating and handling process signals (signal(2), sigprocmask(2), ...)
@swap System calls for enabling/disabling swap devices (swapon(2), swapoff(2))
@sync Synchronizing files and memory to disk: (fsync(2), msync(2), and related calls)
@timer System calls for scheduling operations by time (alarm(2), timer_create(2), ...)

Note, that as new system calls are added to the kernel, additional system calls might be added to the groups above. Contents of the sets may also change between systemd versions. In addition, the list of system calls depends on the kernel version and architecture for which systemd was compiled. Use systemd-analyze syscall-filter to list the actual list of system calls in each filter.

It is recommended to combine the file system namespacing related options with SystemCallFilter=~@mount, in order to prohibit the unit's processes to undo the mappings. Specifically these are the options PrivateTmp=, PrivateDevices=, ProtectSystem=, ProtectHome=, ProtectKernelTunables=, ProtectControlGroups=, ReadOnlyPaths=, InaccessiblePaths= and ReadWritePaths=.

SystemCallErrorNumber=

Takes an "errno" error number (between 1 and 4095) or errno name such as EPERM, EACCES or EUCLEAN, to return when the system call filter configured with SystemCallFilter= is triggered, instead of terminating the process immediately. When this setting is not used, or when the empty string is assigned, the process will be terminated immediately when the filter is triggered.

SystemCallArchitectures=

Takes a space-separated list of architecture identifiers to include in the system call filter. The known architecture identifiers are the same as for ConditionArchitecture= described in systemd.unit(5), as well as x32, mips64-n32, mips64-le-n32, and the special identifier native. Only system calls of the specified architectures will be permitted to processes of this unit. This is an effective way to disable compatibility with non-native architectures for processes, for example to prohibit execution of 32-bit x86 binaries on 64-bit x86-64 systems. The special native identifier implicitly maps to the native architecture of the system (or more strictly: to the architecture the system manager is compiled for). If running in user mode, or in system mode, but without the CAP_SYS_ADMIN capability (e.g. setting User=nobody), NoNewPrivileges=yes is implied. Note that setting this option to a non-empty list implies that native is included too. By default, this option is set to the empty list, i.e. no system call architecture filtering is applied.

Note that system call filtering is not equally effective on all architectures. For example, on x86 filtering of network socket-related calls is not possible, due to ABI limitations --- a limitation that x86-64 does not have, however. On systems supporting multiple ABIs at the same time --- such as x86/x86-64 --- it is hence recommended to limit the set of permitted system call architectures so that secondary ABIs may not be used to circumvent the restrictions applied to the native ABI of the system. In particular, setting SystemCallArchitectures=native is a good choice for disabling non-native ABIs.

System call architectures may also be restricted system-wide via the SystemCallArchitectures= option in the global configuration. See systemd-system.conf(5) for details.

 

ENVIRONMENT

Environment=

Sets environment variables for executed processes. Takes a space-separated list of variable assignments. This option may be specified more than once, in which case all listed variables will be set. If the same variable is set twice, the later setting will override the earlier setting. If the empty string is assigned to this option, the list of environment variables is reset, all prior assignments have no effect. Variable expansion is not performed inside the strings, however, specifier expansion is possible. The $ character has no special meaning. If you need to assign a value containing spaces or the equals sign to a variable, use double quotes (") for the assignment.

Example:

Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"

gives three variables "VAR1", "VAR2", "VAR3" with the values "word1 word2", "word3", "$word 5 6".

See environ(7) for details about environment variables.

EnvironmentFile=

Similar to Environment= but reads the environment variables from a text file. The text file should contain new-line-separated variable assignments. Empty lines, lines without an "=" separator, or lines starting with ; or # will be ignored, which may be used for commenting. A line ending with a backslash will be concatenated with the following one, allowing multiline variable definitions. The parser strips leading and trailing whitespace from the values of assignments, unless you use double quotes (").

The argument passed should be an absolute filename or wildcard expression, optionally prefixed with "-", which indicates that if the file does not exist, it will not be read and no error or warning message is logged. This option may be specified more than once in which case all specified files are read. If the empty string is assigned to this option, the list of file to read is reset, all prior assignments have no effect.

The files listed with this directive will be read shortly before the process is executed (more specifically, after all processes from a previous unit state terminated. This means you can generate these files in one unit state, and read it with this option in the next).

Settings from these files override settings made with Environment=. If the same variable is set twice from these files, the files will be read in the order they are specified and the later setting will override the earlier setting.

PassEnvironment=

Pass environment variables set for the system service manager to executed processes. Takes a space-separated list of variable names. This option may be specified more than once, in which case all listed variables will be passed. If the empty string is assigned to this option, the list of environment variables to pass is reset, all prior assignments have no effect. Variables specified that are not set for the system manager will not be passed and will be silently ignored. Note that this option is only relevant for the system service manager, as system services by default do not automatically inherit any environment variables set for the service manager itself. However, in case of the user service manager all environment variables are passed to the executed processes anyway, hence this option is without effect for the user service manager.

Variables set for invoked processes due to this setting are subject to being overridden by those configured with Environment= or EnvironmentFile=.

Example:

PassEnvironment=VAR1 VAR2 VAR3

passes three variables "VAR1", "VAR2", "VAR3" with the values set for those variables in PID1.

See environ(7) for details about environment variables.

UnsetEnvironment=

Explicitly unset environment variable assignments that would normally be passed from the service manager to invoked processes of this unit. Takes a space-separated list of variable names or variable assignments. This option may be specified more than once, in which case all listed variables/assignments will be unset. If the empty string is assigned to this option, the list of environment variables/assignments to unset is reset. If a variable assignment is specified (that is: a variable name, followed by "=", followed by its value), then any environment variable matching this precise assignment is removed. If a variable name is specified (that is a variable name without any following "=" or value), then any assignment matching the variable name, regardless of its value is removed. Note that the effect of UnsetEnvironment= is applied as final step when the environment list passed to executed processes is compiled. That means it may undo assignments from any configuration source, including assignments made through Environment= or EnvironmentFile=, inherited from the system manager's global set of environment variables, inherited via PassEnvironment=, set by the service manager itself (such as $NOTIFY_SOCKET and such), or set by a PAM module (in case PAMName= is used).

See environ(7) for details about environment variables.

 

LOGGING AND STANDARD INPUT/OUTPUT

StandardInput=

Controls where file descriptor 0 (STDIN) of the executed processes is connected to. Takes one of null, tty, tty-force, tty-fail, data, file:path, socket or fd:name.

If null is selected, standard input will be connected to /dev/null, i.e. all read attempts by the process will result in immediate EOF.

If tty is selected, standard input is connected to a TTY (as configured by TTYPath=, see below) and the executed process becomes the controlling process of the terminal. If the terminal is already being controlled by another process, the executed process waits until the current controlling process releases the terminal.

tty-force is similar to tty, but the executed process is forcefully and immediately made the controlling process of the terminal, potentially removing previous controlling processes from the terminal.

tty-fail is similar to tty, but if the terminal already has a controlling process start-up of the executed process fails.

The data option may be used to configure arbitrary textual or binary data to pass via standard input to the executed process. The data to pass is configured via StandardInputText=/StandardInputData= (see below). Note that the actual file descriptor type passed (memory file, regular file, UNIX pipe, ...) might depend on the kernel and available privileges. In any case, the file descriptor is read-only, and when read returns the specified data followed by EOF.

The file:path option may be used to connect a specific file system object to standard input. An absolute path following the ":" character is expected, which may refer to a regular file, a FIFO or special file. If an AF_UNIX socket in the file system is specified, a stream socket is connected to it. The latter is useful for connecting standard input of processes to arbitrary system services.

The socket option is valid in socket-activated services only, and requires the relevant socket unit file (see systemd.socket(5) for details) to have Accept=yes set, or to specify a single socket only. If this option is set, standard input will be connected to the socket the service was activated from, which is primarily useful for compatibility with daemons designed for use with the traditional inetd(8) socket activation daemon.

The fd:name option connects standard input to a specific, named file descriptor provided by a socket unit. The name may be specified as part of this option, following a ":" character (e.g. "fd:foobar"). If no name is specified, the name "stdin" is implied (i.e. "fd" is equivalent to "fd:stdin"). At least one socket unit defining the specified name must be provided via the Sockets= option, and the file descriptor name may differ from the name of its containing socket unit. If multiple matches are found, the first one will be used. See FileDescriptorName= in systemd.socket(5) for more details about named file descriptors and their ordering.

This setting defaults to null.

StandardOutput=

Controls where file descriptor 1 (STDOUT) of the executed processes is connected to. Takes one of inherit, null, tty, journal, syslog, kmsg, journal+console, syslog+console, kmsg+console, file:path, socket or fd:name.

inherit duplicates the file descriptor of standard input for standard output.

null connects standard output to /dev/null, i.e. everything written to it will be lost.

tty connects standard output to a tty (as configured via TTYPath=, see below). If the TTY is used for output only, the executed process will not become the controlling process of the terminal, and will not fail or wait for other processes to release the terminal.

journal connects standard output with the journal which is accessible via journalctl(1). Note that everything that is written to syslog or kmsg (see below) is implicitly stored in the journal as well, the specific two options listed below are hence supersets of this one.

syslog connects standard output to the syslog(3) system syslog service, in addition to the journal. Note that the journal daemon is usually configured to forward everything it receives to syslog anyway, in which case this option is no different from journal.

kmsg connects standard output with the kernel log buffer which is accessible via dmesg(1), in addition to the journal. The journal daemon might be configured to send all logs to kmsg anyway, in which case this option is no different from journal.

journal+console, syslog+console and kmsg+console work in a similar way as the three options above but copy the output to the system console as well.

The file:path option may be used to connect a specific file system object to standard output. The semantics are similar to the same option of StandardInputText=, see above. If standard input and output are directed to the same file path, it is opened only once, for reading as well as writing and duplicated. This is particular useful when the specified path refers to an AF_UNIX socket in the file system, as in that case only a single stream connection is created for both input and output.

socket connects standard output to a socket acquired via socket activation. The semantics are similar to the same option of StandardInput=, see above.

The fd:name option connects standard output to a specific, named file descriptor provided by a socket unit. A name may be specified as part of this option, following a ":" character (e.g. "fd:foobar"). If no name is specified, the name "stdout" is implied (i.e. "fd" is equivalent to "fd:stdout"). At least one socket unit defining the specified name must be provided via the Sockets= option, and the file descriptor name may differ from the name of its containing socket unit. If multiple matches are found, the first one will be used. See FileDescriptorName= in systemd.socket(5) for more details about named descriptors and their ordering.

If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the kernel log buffer, the unit will implicitly gain a dependency of type After= on systemd-journald.socket (also see the "Implicit Dependencies" section above). Also note that in this case stdout (or stderr, see below) will be an AF_UNIX stream socket, and not a pipe or FIFO that can be re-opened. This means when executing shell scripts the construct echo "hello" > /dev/stderr for writing text to stderr will not work. To mitigate this use the construct echo "hello" >&2 instead, which is mostly equivalent and avoids this pitfall.

This setting defaults to the value set with DefaultStandardOutput= in systemd-system.conf(5), which defaults to journal. Note that setting this parameter might result in additional dependencies to be added to the unit (see above).

StandardError=

Controls where file descriptor 2 (STDERR) of the executed processes is connected to. The available options are identical to those of StandardOutput=, with some exceptions: if set to inherit the file descriptor used for standard output is duplicated for standard error, while fd:name will use a default file descriptor name of "stderr".

This setting defaults to the value set with DefaultStandardError= in systemd-system.conf(5), which defaults to inherit. Note that setting this parameter might result in additional dependencies to be added to the unit (see above).

StandardInputText=, StandardInputData=

Configures arbitrary textual or binary data to pass via file descriptor 0 (STDIN) to the executed processes. These settings have no effect unless StandardInput= is set to data. Use this option to embed process input data directly in the unit file.

StandardInputText= accepts arbitrary textual data. C-style escapes for special characters as well as the usual "%"-specifiers are resolved. Each time this setting is used the the specified text is appended to the per-unit data buffer, followed by a newline character (thus every use appends a new line to the end of the buffer). Note that leading and trailing whitespace of lines configured with this option is removed. If an empty line is specified the buffer is cleared (hence, in order to insert an empty line, add an additional "\n" to the end or beginning of a line).

StandardInputData= accepts arbitrary binary data, encoded in m[blue]Base64m[][4]. No escape sequences or specifiers are resolved. Any whitespace in the encoded version is ignored during decoding.

Note that StandardInputText= and StandardInputData= operate on the same data buffer, and may be mixed in order to configure both binary and textual data for the same input stream. The textual or binary data is joined strictly in the order the settings appear in the unit file. Assigning an empty string to either will reset the data buffer.

Please keep in mind that in order to maintain readability long unit file settings may be split into multiple lines, by suffixing each line (except for the last) with a "\" character (see systemd.unit(5) for details). This is particularly useful for large data configured with these two options. Example:

...
StandardInput=data
StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy4KSWNrIGtpZWtl \
                  LCBzdGF1bmUsIHd1bmRyZSBtaXIsCnVmZiBlZW1hbCBqZWh0IHNlIHVmZiBkaWUgVMO8ci4KTmFu \
                  dSwgZGVuayBpY2ssIGljayBkZW5rIG5hbnUhCkpldHogaXNzZSB1ZmYsIGVyc2NodCB3YXIgc2Ug \
                  enUhCkljayBqZWhlIHJhdXMgdW5kIGJsaWNrZSDigJQKdW5kIHdlciBzdGVodCBkcmF1w59lbj8g \
                  SWNrZSEK
...

LogLevelMax=

Configures filtering by log level of log messages generated by this unit. Takes a syslog log level, one of emerg (lowest log level, only highest priority messages), alert, crit, err, warning, notice, info, debug (highest log level, also lowest priority messages). See syslog(3) for details. By default no filtering is applied (i.e. the default maximum log level is debug). Use this option to configure the logging system to drop log messages of a specific service above the specified level. For example, set LogLevelMax=info in order to turn off debug logging of a particularly chatty unit. Note that the the configured level is applied to any log messages written by any of the processes belonging to this unit, sent via any supported logging protocol. The filtering is applied early in the logging pipeline, before any kind of further processing is done. Moreover, messages which pass through this filter successfully might still be dropped by filters applied at a later stage in the logging subsystem. For example, MaxLevelStore= configured in journald.conf(5) might prohibit messages of higher log levels to be stored on disk, even though the per-unit LogLevelMax= permitted it to be processed.

LogExtraFields=

Configures additional log metadata fields to include in all log records generated by processes associated with this unit. This setting takes one or more journal field assignments in the format "FIELD=VALUE" separated by whitespace. See systemd.journal-fields(7) for details on the journal field concept. Even though the underlying journal implementation permits binary field values, this setting accepts only valid UTF-8 values. To include space characters in a journal field value, enclose the assignment in double quotes ("). The usual specifiers are expanded in all assignments (see below). Note that this setting is not only useful for attaching additional metadata to log records of a unit, but given that all fields and values are indexed may also be used to implement cross-unit log record matching. Assign an empty string to reset the list.

SyslogIdentifier=

Sets the process name ("syslog tag") to prefix log lines sent to the logging system or the kernel log buffer with. If not set, defaults to the process name of the executed process. This option is only useful when StandardOutput= or StandardError= are set to journal, syslog or kmsg (or to the same settings in combination with +console) and only applies to log messages written to stdout or stderr.

SyslogFacility=

Sets the syslog facility identifier to use when logging. One of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, local0, local1, local2, local3, local4, local5, local6 or local7. See syslog(3) for details. This option is only useful when StandardOutput= or StandardError= are set to journal, syslog or kmsg (or to the same settings in combination with +console), and only applies to log messages written to stdout or stderr. Defaults to daemon.

SyslogLevel=

The default syslog log level to use when logging to the logging system or the kernel log buffer. One of emerg, alert, crit, err, warning, notice, info, debug. See syslog(3) for details. This option is only useful when StandardOutput= or StandardError= are set to journal, syslog or kmsg (or to the same settings in combination with +console), and only applies to log messages written to stdout or stderr. Note that individual lines output by executed processes may be prefixed with a different log level which can be used to override the default log level specified here. The interpretation of these prefixes may be disabled with SyslogLevelPrefix=, see below. For details, see sd-daemon(3). Defaults to info.

SyslogLevelPrefix=

Takes a boolean argument. If true and StandardOutput= or StandardError= are set to journal, syslog or kmsg (or to the same settings in combination with +console), log lines written by the executed process that are prefixed with a log level will be processed with this log level set but the prefix removed. If set to false, the interpretation of these prefixes is disabled and the logged lines are passed on as-is. This only applies to log messages written to stdout or stderr. For details about this prefixing see sd-daemon(3). Defaults to true.

TTYPath=

Sets the terminal device node to use if standard input, output, or error are connected to a TTY (see above). Defaults to /dev/console.

TTYReset=

Reset the terminal device specified with TTYPath= before and after execution. Defaults to "no".

TTYVHangup=

Disconnect all clients which have opened the terminal device specified with TTYPath= before and after execution. Defaults to "no".

TTYVTDisallocate=

If the terminal device specified with TTYPath= is a virtual console terminal, try to deallocate the TTY before and after execution. This ensures that the screen and scrollback buffer is cleared. Defaults to "no".
 

SYSTEM V COMPATIBILITY

UtmpIdentifier=

Takes a four character identifier string for an utmp(5) and wtmp entry for this service. This should only be set for services such as getty implementations (such as agetty(8)) where utmp/wtmp entries must be created and cleared before and after execution, or for services that shall be executed as if they were run by a getty process (see below). If the configured string is longer than four characters, it is truncated and the terminal four characters are used. This setting interprets %I style string replacements. This setting is unset by default, i.e. no utmp/wtmp entries are created or cleaned up for this service.

UtmpMode=

Takes one of "init", "login" or "user". If UtmpIdentifier= is set, controls which type of utmp(5)/wtmp entries for this service are generated. This setting has no effect unless UtmpIdentifier= is set too. If "init" is set, only an INIT_PROCESS entry is generated and the invoked process must implement a getty-compatible utmp/wtmp logic. If "login" is set, first an INIT_PROCESS entry, followed by a LOGIN_PROCESS entry is generated. In this case, the invoked process must implement a login(1)-compatible utmp/wtmp logic. If "user" is set, first an INIT_PROCESS entry, then a LOGIN_PROCESS entry and finally a USER_PROCESS entry is generated. In this case, the invoked process may be any process that is suitable to be run as session leader. Defaults to "init".
 

ENVIRONMENT VARIABLES IN SPAWNED PROCESSES

Processes started by the service manager are executed with an environment variable block assembled from multiple sources. Processes started by the system service manager generally do not inherit environment variables set for the service manager itself (but this may be altered via PassEnvironment=), but processes started by the user service manager instances generally do inherit all environment variables set for the service manager itself.

For each invoked process the list of environment variables set is compiled from the following sources:

• Variables globally configured for the service manager, using the DefaultEnvironment= setting in systemd-system.conf(5), the kernel command line option systemd.setenv= (see systemd(1)) or via systemctl set-environment (see systemctl(1)).

• Variables defined by the service manager itself (see the list below)

• Variables set in the service manager's own environment variable block (subject to PassEnvironment= for the system service manager)

• Variables set via Environment= in the unit file

• Variables read from files specified via EnvironmentFile= in the unit file

• Variables set by any PAM modules in case PAMName= is in effect, cf. pam_env(8)

If the same environment variables are set by multiple of these sources, the later source --- according to the order of the list above --- wins. Note that as final step all variables listed in UnsetEnvironment= are removed again from the compiled environment variable list, immediately before it is passed to the executed process.

The following select environment variables are set by the service manager itself for each invoked process:

$PATH

Colon-separated list of directories to use when launching executables. systemd uses a fixed value of /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin.

$LANG

Locale. Can be set in locale.conf(5) or on the kernel command line (see systemd(1) and kernel-command-line(7)).

$USER, $LOGNAME, $HOME, $SHELL

User name (twice), home directory, and the login shell. The variables are set for the units that have User= set, which includes user systemd instances. See passwd(5).

$INVOCATION_ID

Contains a randomized, unique 128bit ID identifying each runtime cycle of the unit, formatted as 32 character hexadecimal string. A new ID is assigned each time the unit changes from an inactive state into an activating or active state, and may be used to identify this specific runtime cycle, in particular in data stored offline, such as the journal. The same ID is passed to all processes run as part of the unit.

$XDG_RUNTIME_DIR

The directory for volatile state. Set for the user systemd instance, and also in user sessions. See pam_systemd(8).

$XDG_SESSION_ID, $XDG_SEAT, $XDG_VTNR

The identifier of the session, the seat name, and virtual terminal of the session. Set by pam_systemd(8) for login sessions. $XDG_SEAT and $XDG_VTNR will only be set when attached to a seat and a tty.

$MAINPID

The PID of the unit's main process if it is known. This is only set for control processes as invoked by ExecReload= and similar.

$MANAGERPID

The PID of the user systemd instance, set for processes spawned by it.

$LISTEN_FDS, $LISTEN_PID, $LISTEN_FDNAMES

Information about file descriptors passed to a service for socket activation. See sd_listen_fds(3).

$NOTIFY_SOCKET

The socket sd_notify() talks to. See sd_notify(3).

$WATCHDOG_PID, $WATCHDOG_USEC

Information about watchdog keep-alive notifications. See sd_watchdog_enabled(3).

$TERM

Terminal type, set only for units connected to a terminal (StandardInput=tty, StandardOutput=tty, or StandardError=tty). See termcap(5).

$JOURNAL_STREAM

If the standard output or standard error output of the executed processes are connected to the journal (for example, by setting StandardError=journal) $JOURNAL_STREAM contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a colon (":"). This permits invoked processes to safely detect whether their standard output or standard error output are connected to the journal. The device and inode numbers of the file descriptors should be compared with the values set in the environment variable to determine whether the process output is still connected to the journal. Note that it is generally not sufficient to only check whether $JOURNAL_STREAM is set at all as services might invoke external processes replacing their standard output or standard error output, without unsetting the environment variable.

If both standard output and standard error of the executed processes are connected to the journal via a stream socket, this environment variable will contain information about the standard error stream, as that's usually the preferred destination for log data. (Note that typically the same stream is used for both standard output and standard error, hence very likely the environment variable contains device and inode information matching both stream file descriptors.)

This environment variable is primarily useful to allow services to optionally upgrade their used log protocol to the native journal protocol (using sd_journal_print(3) and other functions) if their standard output or standard error output is connected to the journal anyway, thus enabling delivery of structured metadata along with logged messages.

$SERVICE_RESULT

Only defined for the service unit type, this environment variable is passed to all ExecStop= and ExecStopPost= processes, and encodes the service "result". Currently, the following values are defined:


Table 3. Defined $SERVICE_RESULT values

Value Meaning
"success" The service ran successfully and exited cleanly.
"protocol" A protocol violation occurred: the service did not take the steps required by its unit configuration (specifically what is configured in its Type= setting).
"timeout" One of the steps timed out.
"exit-code" Service process exited with a non-zero exit code; see $EXIT_CODE below for the actual exit code returned.
"signal" A service process was terminated abnormally by a signal, without dumping core. See $EXIT_CODE below for the actual signal causing the termination.
"core-dump" A service process terminated abnormally with a signal and dumped core. See $EXIT_CODE below for the signal causing the termination.
"watchdog" Watchdog keep-alive ping was enabled for the service, but the deadline was missed.
"start-limit-hit" A start limit was defined for the unit and it was hit, causing the unit to fail to start. See systemd.unit(5)'s StartLimitIntervalSec= and StartLimitBurst= for details.
"resources" A catch-all condition in case a system operation failed.

This environment variable is useful to monitor failure or successful termination of a service. Even though this variable is available in both ExecStop= and ExecStopPost=, it is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services that managed to start up correctly, and the latter covers both services that failed during their start-up and those which failed during their runtime.

$EXIT_CODE, $EXIT_STATUS

Only defined for the service unit type, these environment variables are passed to all ExecStop=, ExecStopPost= processes and contain exit status/code information of the main process of the service. For the precise definition of the exit code and status, see wait(2). $EXIT_CODE is one of "exited", "killed", "dumped". $EXIT_STATUS contains the numeric exit code formatted as string if $EXIT_CODE is "exited", and the signal name in all other cases. Note that these environment variables are only set if the service manager succeeded to start and identify the main process of the service.


Table 4. Summary of possible service result variable values

$SERVICE_RESULT $EXIT_CODE $EXIT_STATUS
"success" "exited" "0"
"protocol" not set not set
"exited" "0"
"timeout" "killed" "TERM", "KILL"
"exited" "0", "1", "2", "3", ..., "255"
"exit-code" "exited" "1", "2", "3", ..., "255"
"signal" "killed" "HUP", "INT", "KILL", ...
"core-dump" "dumped" "ABRT", "SEGV", "QUIT", ...
"watchdog" "dumped" "ABRT"
"killed" "TERM", "KILL"
"exited" "0", "1", "2", "3", ..., "255"
"start-limit-hit" not set not set
"resources" any of the above any of the above
Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the "timeout" and "watchdog" rows above only the signals that systemd sends have been included. Moreover, using SuccessExitStatus= additional exit statuses may be declared to indicate clean termination, which is not reflected by this table.

 

PROCESS EXIT CODES

When invoking a unit process the service manager possibly fails to apply the execution parameters configured with the settings above. In that case the already created service process will exit with a non-zero exit code before the configured command line is executed. (Or in other words, the child process possibly exits with these error codes, after having been created by the fork(2) system call, but before the matching execve(2) system call is called.) Specifically, exit codes defined by the C library, by the LSB specification and by the systemd service manager itself are used.

The following basic service exit codes are defined by the C library.


Table 5. Basic C library exit codes

Exit Code Symbolic Name Description
0 EXIT_SUCCESS Generic success code.
1 EXIT_FAILURE Generic failure or unspecified error.

The following service exit codes are defined by the m[blue]LSB specificationm[][5].


Table 6. LSB service exit codes

Exit Code Symbolic Name Description
2 EXIT_INVALIDARGUMENT Invalid or excess arguments.
3 EXIT_NOTIMPLEMENTED Unimplemented feature.
4 EXIT_NOPERMISSION The user has insufficient privileges.
5 EXIT_NOTINSTALLED The program is not installed.
6 EXIT_NOTCONFIGURED The program is not configured.
7 EXIT_NOTRUNNING The program is not running.

The LSB specification suggests that error codes 200 and above are reserved for implementations. Some of them are used by the service manager to indicate problems during process invocation:


Table 7. systemd-specific exit codes

Exit Code Symbolic Name Description
200 EXIT_CHDIR Changing to the requested working directory failed. See WorkingDirectory= above.
201 EXIT_NICE Failed to set up process scheduling priority (nice level). See Nice= above.
202 EXIT_FDS Failed to close unwanted file descriptors, or to adjust passed file descriptors.
203 EXIT_EXEC The actual process execution failed (specifically, the execve(2) system call). Most likely this is caused by a missing or non-accessible executable file.
204 EXIT_MEMORY Failed to perform an action due to memory shortage.
205 EXIT_LIMITS Failed to adjust resource limits. See LimitCPU= and related settings above.
206 EXIT_OOM_ADJUST Failed to adjust the OOM setting. See OOMScoreAdjust= above.
207 EXIT_SIGNAL_MASK Failed to set process signal mask.
208 EXIT_STDIN Failed to set up standard input. See StandardInput= above.
209 EXIT_STDOUT Failed to set up standard output. See StandardOutput= above.
210 EXIT_CHROOT Failed to change root directory (chroot(2)). See RootDirectory=/RootImage= above.
211 EXIT_IOPRIO Failed to set up IO scheduling priority. See IOSchedulingClass=/IOSchedulingPriority= above.
212 EXIT_TIMERSLACK Failed to set up timer slack. See TimerSlackNSec= above.
213 EXIT_SECUREBITS Failed to set process secure bits. See SecureBits= above.
214 EXIT_SETSCHEDULER Failed to set up CPU scheduling. See CPUSchedulingPolicy=/CPUSchedulingPriority= above.
215 EXIT_CPUAFFINITY Failed to set up CPU affinity. See CPUAffinity= above.
216 EXIT_GROUP Failed to determine or change group credentials. See Group=/SupplementaryGroups= above.
217 EXIT_USER Failed to determine or change user credentials, or to set up user namespacing. See User=/PrivateUsers= above.
218 EXIT_CAPABILITIES Failed to drop capabilities, or apply ambient capabilities. See CapabilityBoundingSet=/AmbientCapabilities= above.
219 EXIT_CGROUP Setting up the service control group failed.
220 EXIT_SETSID Failed to create new process session.
221 EXIT_CONFIRM Execution has been cancelled by the user. See the systemd.confirm_spawn= kernel command line setting on kernel-command-line(7) for details.
222 EXIT_STDERR Failed to set up standard error output. See StandardError= above.
224 EXIT_PAM Failed to set up PAM session. See PAMName= above.
225 EXIT_NETWORK Failed to set up network namespacing. See PrivateNetwork= above.
226 EXIT_NAMESPACE Failed to set up mount namespacing. See ReadOnlyPaths= and related settings above.
227 EXIT_NO_NEW_PRIVILEGES Failed to disable new privileges. See NoNewPrivileges=yes above.
228 EXIT_SECCOMP Failed to apply system call filters. See SystemCallFilter= and related settings above.
229 EXIT_SELINUX_CONTEXT Determining or changing SELinux context failed. See SELinuxContext= above.
230 EXIT_PERSONALITY Failed to set up an execution domain (personality). See Personality= above.
231 EXIT_APPARMOR_PROFILE Failed to prepare changing AppArmor profile. See AppArmorProfile= above.
232 EXIT_ADDRESS_FAMILIES Failed to restrict address families. See RestrictAddressFamilies= above.
233 EXIT_RUNTIME_DIRECTORY Setting up runtime directory failed. See RuntimeDirectory= and related settings above.
235 EXIT_CHOWN Failed to adjust socket ownership. Used for socket units only.
236 EXIT_SMACK_PROCESS_LABEL Failed to set SMACK label. See SmackProcessLabel= above.
237 EXIT_KEYRING Failed to set up kernel keyring.
238 EXIT_STATE_DIRECTORY Failed to set up unit's state directory. See StateDirectory= above.
239 EXIT_CACHE_DIRECTORY Failed to set up unit's cache directory. See CacheDirectory= above.
240 EXIT_LOGS_DIRECTORY Failed to set up unit's logging directory. See LogsDirectory= above.
241 EXIT_CONFIGURATION_DIRECTORY Failed to set up unit's configuration directory. See ConfigurationDirectory= above.

 

SEE ALSO

systemd(1), systemctl(1), systemd-analyze(1), journalctl(8), systemd.unit(5), systemd.service(5), systemd.socket(5), systemd.swap(5), systemd.mount(5), systemd.kill(5), systemd.resource-control(5), systemd.time(7), systemd.directives(7), tmpfiles.d(5), exec(3)  

NOTES

1.
Discoverable Partitions Specification
https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/
2.
No New Privileges Flag
https://www.kernel.org/doc/html/latest/userspace-api/no_new_privs.html
3.
proc.txt
https://www.kernel.org/doc/Documentation/filesystems/proc.txt
4.
Base64
https://tools.ietf.org/html/rfc2045#section-6.8
5.
LSB specification
https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
PATHS
CREDENTIALS
CAPABILITIES
SECURITY
MANDATORY ACCESS CONTROL
PROCESS PROPERTIES
SCHEDULING
SANDBOXING
SYSTEM CALL FILTERING
ENVIRONMENT
LOGGING AND STANDARD INPUT/OUTPUT
SYSTEM V COMPATIBILITY
ENVIRONMENT VARIABLES IN SPAWNED PROCESSES
PROCESS EXIT CODES
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:55 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.SERVICE

SYSTEMD.SERVICE

Section: systemd.service (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.service - Service unit configuration  

SYNOPSIS

service.service  

DESCRIPTION

A unit configuration file whose name ends in .service encodes information about a process controlled and supervised by systemd.

This man page lists the configuration options specific to this unit type. See systemd.unit(5) 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.

Additional options are listed in systemd.exec(5), which define the execution environment the commands are executed in, and in systemd.kill(5), which define the way the processes of the service are terminated, and in systemd.resource-control(5), which configure resource control settings for the processes of the service.

If a service is requested under a certain name but no unit configuration file is found, systemd looks for a SysV init script by the same name (with the .service suffix removed) and dynamically creates a service unit from that script. This is useful for compatibility with SysV. Note that this compatibility is quite comprehensive but not 100%. For details about the incompatibilities, see the m[blue]Incompatibilities with SysVm[][1] document.  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• Services with Type=dbus set automatically acquire dependencies of type Requires= and After= on dbus.socket.

• Socket activated services are automatically ordered after their activating .socket units via an automatic After= dependency. Services also pull in all .socket units listed in Sockets= via automatic Wants= and After= dependencies.

Additional implicit dependencies may be added as result of execution and resource control parameters as documented in systemd.exec(5) and systemd.resource-control(5).  

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Service units will have dependencies of type Requires= and After= on sysinit.target, a dependency of type 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.

• Instanced service units (i.e. service units with an "@" in their name) are assigned by default a per-template slice unit (see systemd.slice(5)), named after the template unit, containing all instances of the specific template. This slice is normally stopped at shutdown, together with all template instances. If that is not desired, set DefaultDependencies=no in the template unit, and either define your own per-template slice unit file that also sets DefaultDependencies=no, or set Slice=system.slice (or another suitable slice) in the template unit. Also see systemd.resource-control(5).
 

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 systemd.exec(5), systemd.kill(5) and systemd.resource-control(5). The options specific to the "[Service]" section of service units are the following:

Type=

Configures the process start-up type for this service unit. One of simple, forking, oneshot, dbus, notify or idle.

If set to simple (the default if neither Type= nor BusName=, but ExecStart= are specified), it is expected that the process configured with ExecStart= is the main process of the service. In this mode, if the process offers functionality to other processes on the system, its communication channels should be installed before the daemon is started up (e.g. sockets set up by systemd, via socket activation), as systemd will immediately proceed starting follow-up units.

If set to forking, it is expected that the process configured with ExecStart= will call fork() as part of its start-up. The parent process is expected to exit when start-up is complete and all communication channels are set up. The child continues to run as the main daemon process. This is the behavior of traditional UNIX daemons. If this setting is used, it is recommended to also use the PIDFile= option, so that systemd can identify the main process of the daemon. systemd will proceed with starting follow-up units as soon as the parent process exits.

Behavior of oneshot is similar to simple; however, it is expected that the process has to exit before systemd starts follow-up units. RemainAfterExit= is particularly useful for this type of service. This is the implied default if neither Type= nor ExecStart= are specified.

Behavior of dbus is similar to simple; however, it is expected that the daemon acquires a name on the D-Bus bus, as configured by BusName=. systemd will proceed with starting follow-up units after the D-Bus bus name has been acquired. Service units with this option configured implicitly gain dependencies on the dbus.socket unit. This type is the default if BusName= is specified.

Behavior of notify is similar to simple; however, it is expected that the daemon sends a notification message via sd_notify(3) or an equivalent call when it has finished starting up. systemd will proceed with starting follow-up units after this notification message has been sent. If this option is used, NotifyAccess= (see below) should be set to open access to the notification socket provided by systemd. If NotifyAccess= is missing or set to none, it will be forcibly set to main. Note that currently Type=notify will not work if used in combination with PrivateNetwork=yes.

Behavior of idle is very similar to simple; however, actual execution of the service program is delayed until all active jobs are dispatched. This may be used to avoid interleaving of output of shell services with the status output on the console. Note that this type is useful only to improve console output, it is not useful as a general unit ordering tool, and the effect of this service type is subject to a 5s time-out, after which the service program is invoked anyway.

RemainAfterExit=

Takes a boolean value that specifies whether the service shall be considered active even when all its processes exited. Defaults to no.

GuessMainPID=

Takes a boolean value that specifies whether systemd should try to guess the main PID of a service if it cannot be determined reliably. This option is ignored unless Type=forking is set and PIDFile= is unset because for the other types or with an explicitly configured PID file, the main PID is always known. The guessing algorithm might come to incorrect conclusions if a daemon consists of more than one process. If the main PID cannot be determined, failure detection and automatic restarting of a service will not work reliably. Defaults to yes.

PIDFile=

Takes an absolute path referring to the PID file of the service. Usage of this option is recommended for services where Type= is set to forking. The service manager will read the PID of the main process of the service from this file after start-up of the service. The service manager will not write to the file configured here, although it will remove the file after the service has shut down if it still exists. The PID file does not need to be owned by a privileged user, but if it is owned by an unprivileged user additional safety restrictions are enforced: the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the PID file must refer to a process already belonging to the service.

BusName=

Takes a D-Bus bus name that this service is reachable as. This option is mandatory for services where Type= is set to dbus.

ExecStart=

Commands with their arguments that are executed when this service is started. The value is split into zero or more command lines according to the rules described below (see section "Command Lines" below).

Unless Type= is oneshot, exactly one command must be given. When Type=oneshot is used, zero or more commands may be specified. Commands may be specified by providing multiple command lines in the same directive, or alternatively, this directive may be specified more than once with the same effect. If the empty string is assigned to this option, the list of commands to start is reset, prior assignments of this option will have no effect. If no ExecStart= is specified, then the service must have RemainAfterExit=yes and at least one ExecStop= line set. (Services lacking both ExecStart= and ExecStop= are not valid.)

For each of the specified commands, the first argument must be an absolute path to an executable. Optionally, this filename may be prefixed with a number of special characters:


Table 1. Special executable prefixes

Prefix Effect
"@" If the executable path is prefixed with "@", the second specified token will be passed as "argv[0]" to the executed process (instead of the actual filename), followed by the further arguments specified.
"-" If the executable path is prefixed with "-", an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is ignored and considered success.
"+" If the executable path is prefixed with "+" then the process is executed with full privileges. In this mode privilege restrictions configured with User=, Group=, CapabilityBoundingSet= or the various file system namespacing options (such as PrivateDevices=, PrivateTmp=) are not applied to the invoked command line (but still affect any other ExecStart=, ExecStop=, ... lines).
"!" Similar to the "+" character discussed above this permits invoking command lines with elevated privileges. However, unlike "+" the "!" character exclusively alters the effect of User=, Group= and SupplementaryGroups=, i.e. only the stanzas the affect user and group credentials. Note that this setting may be combined with DynamicUser=, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself.
"!!" This prefix is very similar to "!", however it only has an effect on systems lacking support for ambient process capabilities, i.e. without support for AmbientCapabilities=. It's intended to be used for unit files that take benefit of ambient capabilities to run processes with minimal privileges wherever possible while remaining compatible with systems that lack ambient capabilities support. Note that when "!!" is used, and a system lacking ambient capability support is detected any configured SystemCallFilter= and CapabilityBoundingSet= stanzas are implicitly modified, in order to permit spawned processes to drop credentials and capabilities themselves, even if this is configured to not be allowed. Moreover, if this prefix is used and a system lacking ambient capability support is detected AmbientCapabilities= will be skipped and not be applied. On systems supporting ambient capabilities, "!!" has no effect and is redundant.

"@", "-", and one of "+"/"!"/"!!" may be used together and they can appear in any order. However, only one of "+", "!", "!!" may be used at a time. Note that these prefixes are also supported for the other command line settings, i.e. ExecStartPre=, ExecStartPost=, ExecReload=, ExecStop= and ExecStopPost=.

If more than one command is specified, the commands are invoked sequentially in the order they appear in the unit file. If one of the commands fails (and is not prefixed with "-"), other lines are not executed, and the unit is considered failed.

Unless Type=forking is set, the process started via this command line will be considered the main process of the daemon.

ExecStartPre=, ExecStartPost=

Additional commands that are executed before or after the command in ExecStart=, respectively. Syntax is the same as for ExecStart=, except that multiple command lines are allowed and the commands are executed one after the other, serially.

If any of those commands (not prefixed with "-") fail, the rest are not executed and the unit is considered failed.

ExecStart= commands are only run after all ExecStartPre= commands that were not prefixed with a "-" exit successfully.

ExecStartPost= commands are only run after the commands specified in ExecStart= have been invoked successfully, as determined by Type= (i.e. the process has been started for Type=simple or Type=idle, the last ExecStart= process exited successfully for Type=oneshot, the initial process exited successfully for Type=forking, "READY=1" is sent for Type=notify, or the BusName= has been taken for Type=dbus).

Note that ExecStartPre= may not be used to start long-running processes. All processes forked off by processes invoked via ExecStartPre= will be killed before the next service process is run.

Note that if any of the commands specified in ExecStartPre=, ExecStart=, or ExecStartPost= fail (and are not prefixed with "-", see above) or time out before the service is fully up, execution continues with commands specified in ExecStopPost=, the commands in ExecStop= are skipped.

ExecReload=

Commands to execute to trigger a configuration reload in the service. This argument takes multiple command lines, following the same scheme as described for ExecStart= above. Use of this setting is optional. Specifier and environment variable substitution is supported here following the same scheme as for ExecStart=.

One additional, special environment variable is set: if known, $MAINPID is set to the main process of the daemon, and may be used for command lines like the following:

/bin/kill -HUP $MAINPID

Note however that reloading a daemon by sending a signal (as with the example line above) is usually not a good choice, because this is an asynchronous operation and hence not suitable to order reloads of multiple services against each other. It is strongly recommended to set ExecReload= to a command that not only triggers a configuration reload of the daemon, but also synchronously waits for it to complete.

ExecStop=

Commands to execute to stop the service started via ExecStart=. This argument takes multiple command lines, following the same scheme as described for ExecStart= above. Use of this setting is optional. After the commands configured in this option are run, it is implied that the service is stopped, and any processes remaining for it are terminated according to the KillMode= setting (see systemd.kill(5)). If this option is not specified, the process is terminated by sending the signal specified in KillSignal= when service stop is requested. Specifier and environment variable substitution is supported (including $MAINPID, see above).

Note that it is usually not sufficient to specify a command for this setting that only asks the service to terminate (for example, by queuing some form of termination signal for it), but does not wait for it to do so. Since the remaining processes of the services are killed according to KillMode= and KillSignal= as described above immediately after the command exited, this may not result in a clean stop. The specified command should hence be a synchronous operation, not an asynchronous one.

Note that the commands specified in ExecStop= are only executed when the service started successfully first. They are not invoked if the service was never started at all, or in case its start-up failed, for example because any of the commands specified in ExecStart=, ExecStartPre= or ExecStartPost= failed (and weren't prefixed with "-", see above) or timed out. Use ExecStopPost= to invoke commands when a service failed to start up correctly and is shut down again. Also note that, service restart requests are implemented as stop operations followed by start operations. This means that ExecStop= and ExecStopPost= are executed during a service restart operation.

It is recommended to use this setting for commands that communicate with the service requesting clean termination. When the commands specified with this option are executed it should be assumed that the service is still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use ExecStopPost= instead.

ExecStopPost=

Additional commands that are executed after the service is stopped. This includes cases where the commands configured in ExecStop= were used, where the service does not have any ExecStop= defined, or where the service exited unexpectedly. This argument takes multiple command lines, following the same scheme as described for ExecStart=. Use of these settings is optional. Specifier and environment variable substitution is supported. Note that - unlike ExecStop= - commands specified with this setting are invoked when a service failed to start up correctly and is shut down again.

It is recommended to use this setting for clean-up operations that shall be executed even when the service failed to start up correctly. Commands configured with this setting need to be able to operate even if the service failed starting up half-way and left incompletely initialized data around. As the service's processes have been terminated already when the commands specified with this setting are executed they should not attempt to communicate with them.

Note that all commands that are configured with this setting are invoked with the result code of the service, as well as the main process' exit code and status, set in the $SERVICE_RESULT, $EXIT_CODE and $EXIT_STATUS environment variables, see systemd.exec(5) for details.

RestartSec=

Configures the time to sleep before restarting a service (as configured with Restart=). Takes a unit-less value in seconds, or a time span value such as "5min 20s". Defaults to 100ms.

TimeoutStartSec=

Configures the time to wait for start-up. If a daemon service does not signal start-up completion within the configured time, the service will be considered failed and will be shut down again. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass "infinity" to disable the timeout logic. Defaults to DefaultTimeoutStartSec= from the manager configuration file, except when Type=oneshot is used, in which case the timeout is disabled by default (see systemd-system.conf(5)).

If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this may cause the start time to be extended beyond TimeoutStartSec=. The first receipt of this message must occur before TimeoutStartSec= is exceeded, and once the start time has exended beyond TimeoutStartSec=, the service manager will allow the service to continue to start, provided the service repeats "EXTEND_TIMEOUT_USEC=..." within the interval specified until the service startup status is finished by "READY=1". (see sd_notify(3)).

TimeoutStopSec=

Configures the time to wait for stop. If a service is asked to stop, but does not terminate in the specified time, it will be terminated forcibly via SIGTERM, and after another timeout of equal duration with SIGKILL (see KillMode= in systemd.kill(5)). Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass "infinity" to disable the timeout logic. Defaults to DefaultTimeoutStopSec= from the manager configuration file (see systemd-system.conf(5)).

If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this may cause the stop time to be extended beyond TimeoutStopSec=. The first receipt of this message must occur before TimeoutStopSec= is exceeded, and once the stop time has exended beyond TimeoutStopSec=, the service manager will allow the service to continue to stop, provided the service repeats "EXTEND_TIMEOUT_USEC=..." within the interval specified, or terminates itself (see sd_notify(3)).

TimeoutSec=

A shorthand for configuring both TimeoutStartSec= and TimeoutStopSec= to the specified value.

RuntimeMaxSec=

Configures a maximum time for the service to run. If this is used and the service has been active for longer than the specified time it is terminated and put into a failure state. Note that this setting does not have any effect on Type=oneshot services, as they terminate immediately after activation completed. Pass "infinity" (the default) to configure no runtime limit.

If a service of Type=notify sends "EXTEND_TIMEOUT_USEC=...", this may cause the runtime to be extended beyond RuntimeMaxSec=. The first receipt of this message must occur before RuntimeMaxSec= is exceeded, and once the runtime has exended beyond RuntimeMaxSec=, the service manager will allow the service to continue to run, provided the service repeats "EXTEND_TIMEOUT_USEC=..." within the interval specified until the service shutdown is acheived by "STOPPING=1" (or termination). (see sd_notify(3)).

WatchdogSec=

Configures the watchdog timeout for a service. The watchdog is activated when the start-up is completed. The service must call sd_notify(3) regularly with "WATCHDOG=1" (i.e. the "keep-alive ping"). If the time between two such calls is larger than the configured time, then the service is placed in a failed state and it will be terminated with SIGABRT. By setting Restart= to on-failure, on-watchdog, on-abnormal or always, the service will be automatically restarted. The time configured here will be passed to the executed service process in the WATCHDOG_USEC= environment variable. This allows daemons to automatically enable the keep-alive pinging logic if watchdog support is enabled for the service. If this option is used, NotifyAccess= (see below) should be set to open access to the notification socket provided by systemd. If NotifyAccess= is not set, it will be implicitly set to main. Defaults to 0, which disables this feature. The service can check whether the service manager expects watchdog keep-alive notifications. See sd_watchdog_enabled(3) for details. sd_event_set_watchdog(3) may be used to enable automatic watchdog notification support.

Restart=

Configures whether the service shall be restarted when the service process exits, is killed, or a timeout is reached. The service process may be the main service process, but it may also be one of the processes specified with ExecStartPre=, ExecStartPost=, ExecStop=, ExecStopPost=, or ExecReload=. When the death of the process is a result of systemd operation (e.g. service stop or restart), the service will not be restarted. Timeouts include missing the watchdog "keep-alive ping" deadline and a service start, reload, and stop operation timeouts.

Takes one of no, on-success, on-failure, on-abnormal, on-watchdog, on-abort, or always. If set to no (the default), the service will not be restarted. If set to on-success, it will be restarted only when the service process exits cleanly. In this context, a clean exit means an exit code of 0, or one of the signals SIGHUP, SIGINT, SIGTERM or SIGPIPE, and additionally, exit statuses and signals specified in SuccessExitStatus=. If set to on-failure, the service will be restarted when the process exits with a non-zero exit code, is terminated by a signal (including on core dump, but excluding the aforementioned four signals), when an operation (such as service reload) times out, and when the configured watchdog timeout is triggered. If set to on-abnormal, the service will be restarted when the process is terminated by a signal (including on core dump, excluding the aforementioned four signals), when an operation times out, or when the watchdog timeout is triggered. If set to on-abort, the service will be restarted only if the service process exits due to an uncaught signal not specified as a clean exit status. If set to on-watchdog, the service will be restarted only if the watchdog timeout for the service expires. If set to always, the service will be restarted regardless of whether it exited cleanly or not, got terminated abnormally by a signal, or hit a timeout.


Table 2. Exit causes and the effect of the Restart= settings on them

Restart settings/Exit causes no always on-success on-failure on-abnormal on-abort on-watchdog
Clean exit code or signal   X X        
Unclean exit code   X   X      
Unclean signal   X   X X X  
Timeout   X   X X    
Watchdog   X   X X   X

As exceptions to the setting above, the service will not be restarted if the exit code or signal is specified in RestartPreventExitStatus= (see below) or the service is stopped with systemctl stop or an equivalent operation. Also, the services will always be restarted if the exit code or signal is specified in RestartForceExitStatus= (see below).

Note that service restart is subject to unit start rate limiting configured with StartLimitIntervalSec= and StartLimitBurst=, see systemd.unit(5) for details. A restarted service enters the failed state only after the start limits are reached.

Setting this to on-failure is the recommended choice for long-running services, in order to increase reliability by attempting automatic recovery from errors. For services that shall be able to terminate on their own choice (and avoid immediate restarting), on-abnormal is an alternative choice.

SuccessExitStatus=

Takes a list of exit status definitions that, when returned by the main service process, will be considered successful termination, in addition to the normal successful exit code 0 and the signals SIGHUP, SIGINT, SIGTERM, and SIGPIPE. Exit status definitions can either be numeric exit codes or termination signal names, separated by spaces. For example:

SuccessExitStatus=1 2 8 SIGKILL

ensures that exit codes 1, 2, 8 and the termination signal SIGKILL are considered clean service terminations.

This option may appear more than once, in which case the list of successful exit statuses is merged. If the empty string is assigned to this option, the list is reset, all prior assignments of this option will have no effect.

RestartPreventExitStatus=

Takes a list of exit status definitions that, when returned by the main service process, will prevent automatic service restarts, regardless of the restart setting configured with Restart=. Exit status definitions can either be numeric exit codes or termination signal names, and are separated by spaces. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart logic. For example:

RestartPreventExitStatus=1 6 SIGABRT

ensures that exit codes 1 and 6 and the termination signal SIGABRT will not result in automatic service restarting. This option may appear more than once, in which case the list of restart-preventing statuses is merged. If the empty string is assigned to this option, the list is reset and all prior assignments of this option will have no effect.

RestartForceExitStatus=

Takes a list of exit status definitions that, when returned by the main service process, will force automatic service restarts, regardless of the restart setting configured with Restart=. The argument format is similar to RestartPreventExitStatus=.

PermissionsStartOnly=

Takes a boolean argument. If true, the permission-related execution options, as configured with User= and similar options (see systemd.exec(5) for more information), are only applied to the process started with ExecStart=, and not to the various other ExecStartPre=, ExecStartPost=, ExecReload=, ExecStop=, and ExecStopPost= commands. If false, the setting is applied to all configured commands the same way. Defaults to false.

RootDirectoryStartOnly=

Takes a boolean argument. If true, the root directory, as configured with the RootDirectory= option (see systemd.exec(5) for more information), is only applied to the process started with ExecStart=, and not to the various other ExecStartPre=, ExecStartPost=, ExecReload=, ExecStop=, and ExecStopPost= commands. If false, the setting is applied to all configured commands the same way. Defaults to false.

NonBlocking=

Set the O_NONBLOCK flag for all file descriptors passed via socket-based activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr), excluding those passed in via the file descriptor storage logic (see FileDescriptorStoreMax= for details), will have the O_NONBLOCK flag set and hence are in non-blocking mode. This option is only useful in conjunction with a socket unit, as described in systemd.socket(5) and has no effect on file descriptors which were previously saved in the file-descriptor store for example. Defaults to false.

NotifyAccess=

Controls access to the service status notification socket, as accessible via the sd_notify(3) call. Takes one of none (the default), main, exec or all. If none, no daemon status updates are accepted from the service processes, all status update messages are ignored. If main, only service updates sent from the main process of the service are accepted. If exec, only service updates sent from any of the main or control processes originating from one of the Exec*= commands are accepted. If all, all services updates from all members of the service's control group are accepted. This option should be set to open access to the notification socket when using Type=notify or WatchdogSec= (see above). If those options are used but NotifyAccess= is not configured, it will be implicitly set to main.

Note that sd_notify() notifications may be attributed to units correctly only if either the sending process is still around at the time PID 1 processes the message, or if the sending process is explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked off the process, i.e. on all processes that match main or exec. Conversely, if an auxiliary process of the unit sends an sd_notify() message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if NotifyAccess=all is set for it.

Sockets=

Specifies the name of the socket units this service shall inherit socket file descriptors from when the service is started. Normally, it should not be necessary to use this setting, as all socket file descriptors whose unit shares the same name as the service (subject to the different unit name suffix of course) are passed to the spawned process.

Note that the same socket file descriptors may be passed to multiple processes simultaneously. Also note that a different service may be activated on incoming socket traffic than the one which is ultimately configured to inherit the socket file descriptors. Or, in other words: the Service= setting of .socket units does not have to match the inverse of the Sockets= setting of the .service it refers to.

This option may appear more than once, in which case the list of socket units is merged. If the empty string is assigned to this option, the list of sockets is reset, and all prior uses of this setting will have no effect.

FileDescriptorStoreMax=

Configure how many file descriptors may be stored in the service manager for the service using sd_pid_notify_with_fds(3)'s "FDSTORE=1" messages. This is useful for implementing services that can restart after an explicit request or a crash without losing state. Any open sockets and other file descriptors which should not be closed during the restart may be stored this way. Application state can either be serialized to a file in /run, or better, stored in a memfd_create(2) memory file descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service manager. All file descriptors passed to the service manager from a specific service are passed back to the service's main process on the next service restart. Any file descriptors passed to the service manager are automatically closed when POLLHUP or POLLERR is seen on them, or when the service is fully stopped and no job is queued or being executed for it.

USBFunctionDescriptors=

Configure the location of a file containing m[blue]USB FunctionFSm[][2] descriptors, for implementation of USB gadget functions. This is used only in conjunction with a socket unit with ListenUSBFunction= configured. The contents of this file are written to the ep0 file after it is opened.

USBFunctionStrings=

Configure the location of a file containing USB FunctionFS strings. Behavior is similar to USBFunctionDescriptors= above.

Check systemd.exec(5) and systemd.kill(5) for more settings.  

COMMAND LINES

This section describes command line parsing and variable and specifier substitutions for ExecStart=, ExecStartPre=, ExecStartPost=, ExecReload=, ExecStop=, and ExecStopPost= options.

Multiple command lines may be concatenated in a single directive by separating them with semicolons (these semicolons must be passed as separate words). Lone semicolons may be escaped as "\;".

Each command line is split on whitespace, with the first item being the command to execute, and the subsequent items being the arguments. Double quotes ("...") and single quotes ('...') may be used to wrap a whole item (the opening quote may appear only at the beginning or after whitespace that is not quoted, and the closing quote must be followed by whitespace or the end of line), in which case everything until the next matching quote becomes part of the same argument. Quotes themselves are removed. C-style escapes are also supported. The table below contains the list of known escape patterns. Only escape patterns which match the syntax in the table are allowed; other patterns may be added in the future and unknown patterns will result in a warning. In particular, any backslashes should be doubled. Finally, a trailing backslash ("\") may be used to merge lines.

This syntax is inspired by shell syntax, but only the meta-characters and expansions described in the following paragraphs are understood, and the expansion of variables is different. Specifically, redirection using "<", "<<", ">", and ">>", pipes using "|", running programs in the background using "&", and other elements of shell syntax are not supported.

The command to execute must be an absolute path name. It may contain spaces, but control characters are not allowed.

The command line accepts "%" specifiers as described in systemd.unit(5). Note that the first argument of the command line (i.e. the program to execute) may not include specifiers.

Basic environment variable substitution is supported. Use "${FOO}" as part of a word, or as a word of its own, on the command line, in which case it will be replaced by the value of the environment variable including all whitespace it contains, resulting in a single argument. Use "$FOO" as a separate word on the command line, in which case it will be replaced by the value of the environment variable split at whitespace, resulting in zero or more arguments. For this type of expansion, quotes are respected when splitting into words, and afterwards removed.

Example:

Environment="ONE=one" 'TWO=two two'
ExecStart=/bin/echo $ONE $TWO ${TWO}

This will execute /bin/echo with four arguments: "one", "two", "two", and "two two".

Example:

Environment=ONE='one' "TWO='two two' too" THREE=
ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
ExecStart=/bin/echo $ONE $TWO $THREE

This results in echo being called twice, the first time with arguments "'one'", "'two two' too", "", and the second time with arguments "one", "two two", "too".

To pass a literal dollar sign, use "$$". Variables whose value is not known at expansion time are treated as empty strings. Note that the first argument (i.e. the program to execute) may not be a variable.

Variables to be used in this fashion may be defined through Environment= and EnvironmentFile=. In addition, variables listed in the section "Environment variables in spawned processes" in systemd.exec(5), which are considered "static configuration", may be used (this includes e.g. $USER, but not $TERM).

Note that shell command lines are not directly supported. If shell command lines are to be used, they need to be passed explicitly to a shell implementation of some kind. Example:

ExecStart=/bin/sh -c 'dmesg | tac'

Example:

ExecStart=/bin/echo one ; /bin/echo "two two"

This will execute /bin/echo two times, each time with one argument: "one" and "two two", respectively. Because two commands are specified, Type=oneshot must be used.

Example:

ExecStart=/bin/echo / >/dev/null & \; \
/bin/ls

This will execute /bin/echo with five arguments: "/", ">/dev/null", "&", ";", and "/bin/ls".


Table 3. C escapes supported in command lines and environment variables

Literal Actual value
"\a" bell
"\b" backspace
"\f" form feed
"\n" newline
"\r" carriage return
"\t" tab
"\v" vertical tab
"\\" backslash
"\"" double quotation mark
"\'" single quotation mark
"\s" space
"\xxx" character number xx in hexadecimal encoding
"\nnn" character number nnn in octal encoding

 

EXAMPLES

Example 1. Simple service

The following unit file creates a service that will execute /usr/sbin/foo-daemon. Since no Type= is specified, the default Type=simple will be assumed. systemd will assume the unit to be started immediately after the program has begun executing.

[Unit]
Description=Foo

[Service]
ExecStart=/usr/sbin/foo-daemon

[Install]
WantedBy=multi-user.target

Note that systemd assumes here that the process started by systemd will continue running until the service terminates. If the program daemonizes itself (i.e. forks), please use Type=forking instead.

Since no ExecStop= was specified, systemd will send SIGTERM to all processes started from this service, and after a timeout also SIGKILL. This behavior can be modified, see systemd.kill(5) for details.

Note that this unit type does not include any type of notification when a service has completed initialization. For this, you should use other unit types, such as Type=notify if the service understands systemd's notification protocol, Type=forking if the service can background itself or Type=dbus if the unit acquires a DBus name once initialization is complete. See below.

Example 2. Oneshot service

Sometimes, units should just execute an action without keeping active processes, such as a filesystem check or a cleanup action on boot. For this, Type=oneshot exists. Units of this type will wait until the process specified terminates and then fall back to being inactive. The following unit will perform a cleanup action:

[Unit]
Description=Cleanup old Foo data

[Service]
Type=oneshot
ExecStart=/usr/sbin/foo-cleanup

[Install]
WantedBy=multi-user.target

Note that systemd will consider the unit to be in the state "starting" until the program has terminated, so ordered dependencies will wait for the program to finish before starting themselves. The unit will revert to the "inactive" state after the execution is done, never reaching the "active" state. That means another request to start the unit will perform the action again.

Type=oneshot are the only service units that may have more than one ExecStart= specified. They will be executed in order until either they are all successful or one of them fails.

Example 3. Stoppable oneshot service

Similarly to the oneshot services, there are sometimes units that need to execute a program to set up something and then execute another to shut it down, but no process remains active while they are considered "started". Network configuration can sometimes fall into this category. Another use case is if a oneshot service shall not be executed each time when they are pulled in as a dependency, but only the first time.

For this, systemd knows the setting RemainAfterExit=yes, which causes systemd to consider the unit to be active if the start action exited successfully. This directive can be used with all types, but is most useful with Type=oneshot and Type=simple. With Type=oneshot, systemd waits until the start action has completed before it considers the unit to be active, so dependencies start only after the start action has succeeded. With Type=simple, dependencies will start immediately after the start action has been dispatched. The following unit provides an example for a simple static firewall.

[Unit]
Description=Simple firewall

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/sbin/simple-firewall-start
ExecStop=/usr/local/sbin/simple-firewall-stop

[Install]
WantedBy=multi-user.target

Since the unit is considered to be running after the start action has exited, invoking systemctl start on that unit again will cause no action to be taken.

Example 4. Traditional forking services

Many traditional daemons/services background (i.e. fork, daemonize) themselves when starting. Set Type=forking in the service's unit file to support this mode of operation. systemd will consider the service to be in the process of initialization while the original program is still running. Once it exits successfully and at least a process remains (and RemainAfterExit=no), the service is considered started.

Often, a traditional daemon only consists of one process. Therefore, if only one process is left after the original process terminates, systemd will consider that process the main process of the service. In that case, the $MAINPID variable will be available in ExecReload=, ExecStop=, etc.

In case more than one process remains, systemd will be unable to determine the main process, so it will not assume there is one. In that case, $MAINPID will not expand to anything. However, if the process decides to write a traditional PID file, systemd will be able to read the main PID from there. Please set PIDFile= accordingly. Note that the daemon should write that file before finishing with its initialization. Otherwise, systemd might try to read the file before it exists.

The following example shows a simple daemon that forks and just starts one process in the background:

[Unit]
Description=Some simple daemon

[Service]
Type=forking
ExecStart=/usr/sbin/my-simple-daemon -d

[Install]
WantedBy=multi-user.target

Please see systemd.kill(5) for details on how you can influence the way systemd terminates the service.

Example 5. DBus services

For services that acquire a name on the DBus system bus, use Type=dbus and set BusName= accordingly. The service should not fork (daemonize). systemd will consider the service to be initialized once the name has been acquired on the system bus. The following example shows a typical DBus service:

[Unit]
Description=Simple DBus service

[Service]
Type=dbus
BusName=org.example.simple-dbus-service
ExecStart=/usr/sbin/simple-dbus-service

[Install]
WantedBy=multi-user.target

For bus-activatable services, do not include a "[Install]" section in the systemd service file, but use the SystemdService= option in the corresponding DBus service file, for example (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service):

[D-BUS Service]
Name=org.example.simple-dbus-service
Exec=/usr/sbin/simple-dbus-service
User=root
SystemdService=simple-dbus-service.service

Please see systemd.kill(5) for details on how you can influence the way systemd terminates the service.

Example 6. Services that notify systemd about their initialization

Type=simple services are really easy to write, but have the major disadvantage of systemd not being able to tell when initialization of the given service is complete. For this reason, systemd supports a simple notification protocol that allows daemons to make systemd aware that they are done initializing. Use Type=notify for this. A typical service file for such a daemon would look like this:

[Unit]
Description=Simple notifying service

[Service]
Type=notify
ExecStart=/usr/sbin/simple-notifying-service

[Install]
WantedBy=multi-user.target

Note that the daemon has to support systemd's notification protocol, else systemd will think the service has not started yet and kill it after a timeout. For an example of how to update daemons to support this protocol transparently, take a look at sd_notify(3). systemd will consider the unit to be in the 'starting' state until a readiness notification has arrived.

Please see systemd.kill(5) for details on how you can influence the way systemd terminates the service.  

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), systemd.exec(5), systemd.resource-control(5), systemd.kill(5), systemd.directives(7)  

NOTES

1.
Incompatibilities with SysV
https://www.freedesktop.org/wiki/Software/systemd/Incompatibilities
2.
USB FunctionFS
https://www.kernel.org/doc/Documentation/usb/functionfs.txt


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
OPTIONS
COMMAND LINES
EXAMPLES
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:55 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.SWAP

SYSTEMD.SWAP

Section: systemd.swap (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.swap - Swap unit configuration  

SYNOPSIS

swap.swap  

DESCRIPTION

A unit configuration file whose name ends in ".swap" encodes information about a swap device or file for memory paging controlled and supervised by systemd.

This man page lists the configuration options specific to this unit type. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The swap specific configuration options are configured in the [Swap] section.

Additional options are listed in systemd.exec(5), which define the execution environment the swapon(8) program is executed in, in systemd.kill(5), which define the way these processes are terminated, and in systemd.resource-control(5), which configure resource control settings for these processes of the unit.

Swap units must be named after the devices or files they control. Example: the swap device /dev/sda5 must be configured in a unit file dev-sda5.swap. For details about the escaping logic used to convert a file system path to a unit name, see systemd.unit(5). Note that swap units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to it.  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• All swap units automatically get the BindsTo= and After= dependencies on the device units or the mount units of the files they are activated from.

Additional implicit dependencies may be added as result of execution and resource control parameters as documented in systemd.exec(5) and systemd.resource-control(5).  

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Swap units automatically acquire a Conflicts= and a Before= dependency on umount.target so that they are deactivated at shutdown as well as a Before=swap.target dependency.
 

FSTAB

Swap units may either be configured via unit files, or via /etc/fstab (see fstab(5) for details). Swaps listed in /etc/fstab will be converted into native units dynamically at boot and when the configuration of the system manager is reloaded. See systemd-fstab-generator(8) for details about the conversion.

If a swap device or file is configured in both /etc/fstab and a unit file, the configuration in the latter takes precedence.

When reading /etc/fstab, a few special options are understood by systemd which influence how dependencies are created for swap units.

noauto, auto

With noauto, the swap unit will not be added as a dependency for swap.target. This means that it will not be activated automatically during boot, unless it is pulled in by some other unit. The auto option has the opposite meaning and is the default.

nofail

With nofail, the swap unit will be only wanted, not required by swap.target. This means that the boot will continue even if this swap device is not activated successfully.
 

OPTIONS

Swap files must include a [Swap] section, which carries information about the swap device 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.exec(5) and systemd.kill(5). The options specific to the [Swap] section of swap units are the following:

What=

Takes an absolute path of a device node or file to use for paging. See swapon(8) for details. If this refers to a device node, a dependency on the respective device unit is automatically created. (See systemd.device(5) for more information.) If this refers to a file, a dependency on the respective mount unit is automatically created. (See systemd.mount(5) for more information.) This option is mandatory. Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as "%%".

Priority=

Swap priority to use when activating the swap device or file. This takes an integer. This setting is optional and ignored when the priority is set by pri= in the Options= key.

Options=

May contain an option string for the swap device. This may be used for controlling discard options among other functionality, if the swap backing device supports the discard or trim operation. (See swapon(8) for more information.) Note that the usual specifier expansion is applied to this setting, literal percent characters should hence be written as "%%".

TimeoutSec=

Configures the time to wait for the swapon command to finish. If a command does not exit within the configured time, the swap will be considered failed and be shut down again. All commands still running will be terminated forcibly via SIGTERM, and after another delay of this time with SIGKILL. (See KillMode= in systemd.kill(5).) Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass "0" to disable the timeout logic. Defaults to DefaultTimeoutStartSec= from the manager configuration file (see systemd-system.conf(5)).

Check systemd.exec(5) and systemd.kill(5) for more settings.  

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), systemd.exec(5), systemd.kill(5), systemd.resource-control(5), systemd.device(5), systemd.mount(5), swapon(8), systemd-fstab-generator(8), systemd.directives(7)


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
FSTAB
OPTIONS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:55 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.AUTOMOUNT

SYSTEMD.AUTOMOUNT

Section: systemd.automount (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.automount - Automount unit configuration  

SYNOPSIS

automount.automount  

DESCRIPTION

A unit configuration file whose name ends in ".automount" encodes information about a file system automount point controlled and supervised by systemd.

This man page lists the configuration options specific to this unit type. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The automount specific configuration options are configured in the [Automount] section.

Automount units must be named after the automount directories they control. Example: the automount point /home/lennart must be configured in a unit file home-lennart.automount. For details about the escaping logic used to convert a file system path to a unit name see systemd.unit(5). Note that automount units cannot be templated, nor is it possible to add multiple names to an automount unit by creating additional symlinks to its unit file.

For each automount unit file a matching mount unit file (see systemd.mount(5) for details) must exist which is activated when the automount path is accessed. Example: if an automount unit home-lennart.automount is active and the user accesses /home/lennart the mount unit home-lennart.mount will be activated.

Automount units may be used to implement on-demand mounting as well as parallelized mounting of file systems.  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• If an automount unit is beneath another mount unit in the file system hierarchy, both a requirement and an ordering dependency between both units are created automatically.

• An implicit Before= dependency is created between an automount unit and the mount unit it activates.
 

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Automount units acquire automatic Before= and Conflicts= on umount.target in order to be stopped during shutdown.
 

FSTAB

Automount units may either be configured via unit files, or via /etc/fstab (see fstab(5) for details).

For details how systemd parses /etc/fstab see systemd.mount(5).

If an automount point is configured in both /etc/fstab and a unit file, the configuration in the latter takes precedence.  

OPTIONS

Automount files must include an [Automount] section, which carries information about the file system automount points it supervises. The options specific to the [Automount] section of automount units are the following:

Where=

Takes an absolute path of a directory of the automount point. If the automount point does not exist at time that the automount point is installed, it is created. This string must be reflected in the unit filename. (See above.) This option is mandatory.

DirectoryMode=

Directories of automount points (and any parent directories) are automatically created if needed. This option specifies the file system access mode used when creating these directories. Takes an access mode in octal notation. Defaults to 0755.

TimeoutIdleSec=

Configures an idle timeout. Once the mount has been idle for the specified time, systemd will attempt to unmount. Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout logic. The timeout is disabled by default.
 

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), systemd.mount(5), mount(8), automount(8), systemd.directives(7)


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
FSTAB
OPTIONS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:56 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.TARGET

SYSTEMD.TARGET

Section: systemd.target (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.target - Target unit configuration  

SYNOPSIS

target.target  

DESCRIPTION

A unit configuration file whose name ends in ".target" encodes information about a target unit of systemd, which is used for grouping units and as well-known synchronization points during start-up.

This unit type has no specific options. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. A separate [Target] section does not exist, since no target-specific options may be configured.

Target units do not offer any additional functionality on top of the generic functionality provided by units. They exist merely to group units via dependencies (useful as boot targets), and to establish standardized names for synchronization points used in 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 special target units such as runlevel3.target exist which are used by the SysV runlevel compatibility code in systemd. See systemd.special(7) for details).  

IMPLICIT DEPENDENCIES

There are no implicit dependencies for target units.  

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Target units will automatically complement all configured dependencies of type Wants= or Requires= with dependencies of type After= unless DefaultDependencies=no is set in the specified units. Note that Wants= or Requires= must be defined in the target unit itself --- if you for example define Wants=some.target in some.service, the automatic ordering will not be added.

• Target units automatically gain Conflicts= dependency against shutdown.target.
 

EXAMPLE

Example 1. Simple standalone target

# emergency-net.target

[Unit]
Description=Emergency Mode with Networking
Requires=emergency.target systemd-networkd.service
After=emergency.target systemd-networkd.service
AllowIsolate=yes

When adding dependencies to other units, it's important to check if they set DefaultDependencies=. Service units, unless they set DefaultDependencies=no, automatically get a dependency on sysinit.target. In this case, both emergency.target and systemd-networkd.service have DefaultDependencies=no, so they are suitable for use in this target, and do not pull in sysinit.target.

You can now switch into this emergency mode by running systemctl isolate emergency-net.target or by passing the option systemd.unit=emergency-net.target on the kernel command line.

Other units can have WantedBy=emergency-net.target in the [Install] section. After they are enabled using systemctl enable, they will be started before emergency-net.target is started. It is also possible to add arbitrary units as dependencies of emergency.target without modifying them by using systemctl add-wants.  

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), systemd.special(7), systemd.directives(7)


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
EXAMPLE
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:56 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.TIMER

SYSTEMD.TIMER

Section: systemd.timer (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.timer - Timer unit configuration  

SYNOPSIS

timer.timer  

DESCRIPTION

A unit configuration file whose name ends in ".timer" encodes information about a timer controlled and supervised by systemd, for timer-based activation.

This man page lists the configuration options specific to this unit type. See systemd.unit(5) for the common options of all unit configuration files. The common configuration items are configured in the generic [Unit] and [Install] sections. The timer specific configuration options are configured in the [Timer] section.

For each timer file, a matching unit file must exist, describing the unit to activate when the timer elapses. By default, a service by the same name as the timer (except for the suffix) is activated. Example: a timer file foo.timer activates a matching service foo.service. The unit to activate may be controlled by Unit= (see below).

Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, but simply left running. There is no concept of spawning new service instances in this case. Due to this, services with RemainAfterExit= set (which stay around continuously even after the service's main process exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and then stay around forever.  

IMPLICIT DEPENDENCIES

The following dependencies are implicitly added:

• Timer units automatically gain a Before= dependency on the service they are supposed to activate.
 

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Timer units will automatically have dependencies of type Requires= and After= on sysinit.target, a dependency of type Before= on timers.target, as well as Conflicts= and Before= on shutdown.target to ensure that they are stopped cleanly prior to system shutdown. Only timer units involved with early boot or late system shutdown should disable the DefaultDependencies= option.

• Timer units with at least one OnCalendar= directive will have an additional After= dependency on time-sync.target to avoid being started before the system clock has been correctly set.
 

OPTIONS

Timer files must include a [Timer] section, which carries information about the timer it defines. The options specific to the [Timer] section of timer units are the following:

OnActiveSec=, OnBootSec=, OnStartupSec=, OnUnitActiveSec=, OnUnitInactiveSec=

Defines monotonic timers relative to different starting points: OnActiveSec= defines a timer relative to the moment the timer itself is activated. OnBootSec= defines a timer relative to when the machine was booted up. OnStartupSec= defines a timer relative to when systemd was first started. OnUnitActiveSec= defines a timer relative to when the unit the timer is activating was last activated. OnUnitInactiveSec= defines a timer relative to when the unit the timer is activating was last deactivated.

Multiple directives may be combined of the same and of different types. For example, by combining OnBootSec= and OnUnitActiveSec=, it is possible to define a timer that elapses in regular intervals and activates a specific service each time.

The arguments to the directives are time spans configured in seconds. Example: "OnBootSec=50" means 50s after boot-up. The argument may also include time units. Example: "OnBootSec=5h 30min" means 5 hours and 30 minutes after boot-up. For details about the syntax of time spans, see systemd.time(7).

If a timer configured with OnBootSec= or OnStartupSec= is already in the past when the timer unit is activated, it will immediately elapse and the configured unit is started. This is not the case for timers defined in the other directives.

These are monotonic timers, independent of wall-clock time and timezones. If the computer is temporarily suspended, the monotonic clock stops too.

If the empty string is assigned to any of these options, the list of timers is reset, and all prior assignments will have no effect.

Note that timers do not necessarily expire at the precise time configured with these settings, as they are subject to the AccuracySec= setting below.

OnCalendar=

Defines realtime (i.e. wallclock) timers with calendar event expressions. See systemd.time(7) for more information on the syntax of calendar event expressions. Otherwise, the semantics are similar to OnActiveSec= and related settings.

Note that timers do not necessarily expire at the precise time configured with this setting, as it is subject to the AccuracySec= setting below.

May be specified more than once.

AccuracySec=

Specify the accuracy the timer shall elapse with. Defaults to 1min. The timer is scheduled to elapse within a time window starting with the time specified in OnCalendar=, OnActiveSec=, OnBootSec=, OnStartupSec=, OnUnitActiveSec= or OnUnitInactiveSec= and ending the time configured with AccuracySec= later. Within this time window, the expiry time will be placed at a host-specific, randomized, but stable position that is synchronized between all local timer units. This is done in order to optimize power consumption to suppress unnecessary CPU wake-ups. To get best accuracy, set this option to 1us. Note that the timer is still subject to the timer slack configured via systemd-system.conf(5)'s TimerSlackNSec= setting. See prctl(2) for details. To optimize power consumption, make sure to set this value as high as possible and as low as necessary.

RandomizedDelaySec=

Delay the timer by a randomly selected, evenly distributed amount of time between 0 and the specified time value. Defaults to 0, indicating that no randomized delay shall be applied. Each timer unit will determine this delay randomly each time it is started, and the delay will simply be added on top of the next determined elapsing time. This is useful to stretch dispatching of similarly configured timer events over a certain amount time, to avoid that they all fire at the same time, possibly resulting in resource congestion. Note the relation to AccuracySec= above: the latter allows the service manager to coalesce timer events within a specified time range in order to minimize wakeups, the former does the opposite: it stretches timer events over a time range, to make it unlikely that they fire simultaneously. If RandomizedDelaySec= and AccuracySec= are used in conjunction, first the randomized delay is added, and then the result is possibly further shifted to coalesce it with other timer events happening on the system. As mentioned above AccuracySec= defaults to 1min and RandomizedDelaySec= to 0, thus encouraging coalescing of timer events. In order to optimally stretch timer events over a certain range of time, make sure to set RandomizedDelaySec= to a higher value, and AccuracySec=1us.

Unit=

The unit to activate when this timer elapses. The argument is a unit name, whose suffix is not ".timer". If not specified, this value defaults to a service that has the same name as the timer unit, except for the suffix. (See above.) It is recommended that the unit name that is activated and the unit name of the timer unit are named identically, except for the suffix.

Persistent=

Takes a boolean argument. If true, the time when the service unit was last triggered is stored on disk. When the timer is activated, the service unit is triggered immediately if it would have been triggered at least once during the time when the timer was inactive. This is useful to catch up on missed runs of the service when the machine was off. Note that this setting only has an effect on timers configured with OnCalendar=. Defaults to false.

WakeSystem=

Takes a boolean argument. If true, an elapsing timer will cause the system to resume from suspend, should it be suspended and if the system supports this. Note that this option will only make sure the system resumes on the appropriate times, it will not take care of suspending it again after any work that is to be done is finished. Defaults to false.

RemainAfterElapse=

Takes a boolean argument. If true, an elapsed timer will stay loaded, and its state remains queriable. If false, an elapsed timer unit that cannot elapse anymore is unloaded. Turning this off is particularly useful for transient timer units that shall disappear after they first elapse. Note that this setting has an effect on repeatedly starting a timer unit that only elapses once: if RemainAfterElapse= is on, it will not be started again, and is guaranteed to elapse only once. However, if RemainAfterElapse= is off, it might be started again if it is already elapsed, and thus be triggered multiple times. Defaults to yes.
 

SEE ALSO

systemd(1), systemctl(1), systemd.unit(5), systemd.service(5), systemd.time(7), systemd.directives(7), systemd-system.conf(5), prctl(2)


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
OPTIONS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:56 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.SCOPE

SYSTEMD.SCOPE

Section: systemd.scope (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.scope - Scope unit configuration  

SYNOPSIS

scope.scope  

DESCRIPTION

Scope units are not configured via unit configuration files, but are only created programmatically using the bus interfaces of systemd. They are named similar to filenames. A unit whose name ends in ".scope" refers to a scope unit. Scopes units manage a set of system processes. Unlike service units, scope units manage externally created processes, and do not fork off processes on its own.

The main purpose of scope units is grouping worker processes of a system service for organization and for managing resources.

systemd-run --scope may be used to easily launch a command in a new scope unit from the command line.

See the m[blue]New Control Group Interfacesm[][1] for an introduction on how to make use of scope units from programs.  

IMPLICIT DEPENDENCIES

Implicit dependencies may be added as result of resource control parameters as documented in systemd.resource-control(5).  

DEFAULT DEPENDENCIES

The following dependencies are added unless DefaultDependencies=no is set:

• Scope units will automatically have dependencies of type Conflicts= and Before= on shutdown.target. These ensure that scope units are removed prior to system shutdown. Only scope units involved with early boot or late system shutdown should disable DefaultDependencies= option.
 

SEE ALSO

systemd(1), systemd-run(1), systemd.unit(5), systemd.resource-control(5), systemd.service(5), systemd.directives(7).  

NOTES

1.
New Control Group Interfaces
https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLICIT DEPENDENCIES
DEFAULT DEPENDENCIES
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:56 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.NETWORK

SYSTEMD.NETWORK

Section: systemd.network (5)
Updated:
Index Return to Main Contents
 

NAME

systemd.network - Network configuration  

SYNOPSIS

network.network  

DESCRIPTION

Network setup is performed by systemd-networkd(8).

The main network file must have the extension .network; other extensions are ignored. Networks are applied to links whenever the links appear.

The .network files are read from the files located in the system network directory /lib/systemd/network, the volatile runtime network directory /run/systemd/network and the local administration network directory /etc/systemd/network. All configuration files are collectively sorted and processed in lexical order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in /etc have the highest priority, files in /run take precedence over files with the same name in /lib. This can be used to override a system-supplied configuration file with a local file if needed. As a special case, an empty file (file size 0) or symlink with the same name pointing to /dev/null disables the configuration file entirely (it is "masked").

Along with the network file foo.network, a "drop-in" directory foo.network.d/ may exist. All files with the suffix ".conf" from this directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers.

In addition to /etc/systemd/network, drop-in ".d" directories can be placed in /lib/systemd/network or /run/systemd/network directories. Drop-in files in /etc take precedence over those in /run which in turn take precedence over those in /lib. Drop-in files under any of these directories take precedence over the main netdev file wherever located. (Of course, since /run is temporary and /usr/lib is for vendors, it is unlikely drop-ins should be used in either of those places.)

Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 nor IPv6LL enabled, shall be considered to have no IPv6 support. IPv6 will be automatically disabled for that interface by writing "1" to /proc/sys/net/ipv6/conf/ifname/disable_ipv6.  

[MATCH] SECTION OPTIONS

The network file contains a "[Match]" section, which determines if a given network file may be applied to a given device; and a "[Network]" section specifying how the device should be configured. The first (in lexical order) of the network files that matches a given device is applied, all later files are ignored, even if they match as well.

A network file is said to match a device if each of the entries in the "[Match]" section matches, or if the section is empty. The following keys are accepted:

MACAddress=

The hardware address of the interface (use full colon-delimited hexadecimal, e.g., 01:23:45:67:89:ab).

Path=

A whitespace-separated list of shell-style globs matching the persistent path, as exposed by the udev property "ID_PATH". If the list is prefixed with a "!", the test is inverted; i.e. it is true when "ID_PATH" does not match any item in the list.

Driver=

A whitespace-separated list of shell-style globs matching the driver currently bound to the device, as exposed by the udev property "DRIVER" of its parent device, or if that is not set the driver as exposed by "ethtool -i" of the device itself. If the list is prefixed with a "!", the test is inverted.

Type=

A whitespace-separated list of shell-style globs matching the device type, as exposed by the udev property "DEVTYPE". If the list is prefixed with a "!", the test is inverted.

Name=

A whitespace-separated list of shell-style globs matching the device name, as exposed by the udev property "INTERFACE". If the list is prefixed with a "!", the test is inverted.

Host=

Matches against the hostname or machine ID of the host. See "ConditionHost=" in systemd.unit(5) for details.

Virtualization=

Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation. See "ConditionVirtualization=" in systemd.unit(5) for details.

KernelCommandLine=

Checks whether a specific kernel command line option is set (or if prefixed with the exclamation mark unset). See "ConditionKernelCommandLine=" in systemd.unit(5) for details.

KernelVersion=

Checks whether the kernel version (as reported by uname -r) matches a certain expression (or if prefixed with the exclamation mark does not match it). See "ConditionKernelVersion=" in systemd.unit(5) for details.

Architecture=

Checks whether the system is running on a specific architecture. See "ConditionArchitecture=" in systemd.unit(5) for details.

KeepConfiguration=

Takes a boolean or one of "static", "dhcp-on-stop", "dhcp". When "static", systemd-networkd will not drop static addresses and routes on starting up process. When set to "dhcp-on-stop", systemd-networkd will not drop addresses and routes on stopping the daemon. When "dhcp", the addresses and routes provided by a DHCP server will never be dropped even if the DHCP lease expires. This is contrary to the DHCP specification, but may be the best choice if, e.g., the root filesystem relies on this connection. The setting "dhcp" implies "dhcp-on-stop", and "yes" implies "dhcp" and "static". Defaults to "dhcp-on-stop".
 

[LINK] SECTION OPTIONS

The "[Link]" section accepts the following keys:

MACAddress=

The hardware address to set for the device.

MTUBytes=

The maximum transmission unit in bytes to set for the device. The usual suffixes K, M, G, are supported and are understood to the base of 1024.

Note that if IPv6 is enabled on the interface, and the MTU is chosen below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value.

ARP=

A boolean. Enables or disables the ARP (low-level Address Resolution Protocol) for this interface. Defaults to unset, which means that the kernel default will be used.

For example, disabling ARP is useful when creating multiple MACVLAN or VLAN virtual interfaces atop a single lower-level physical interface, which will then only serve as a link/"bridge" device aggregating traffic to the same physical link and not participate in the network otherwise.

Unmanaged=

A boolean. When "yes", no attempts are made to bring up or configure matching links, equivalent to when there are no matching network files. Defaults to "no".

This is useful for preventing later matching network files from interfering with certain interfaces that are fully controlled by other applications.

RequiredForOnline=

A boolean. When "yes", the network is deemed required when determining whether the system is online when running "systemd-networkd-wait-online". When "no", the network is ignored when checking for online state. Defaults to "yes".

The network will be brought up normally in all cases, but in the event that there is no address being assigned by DHCP or the cable is not plugged in, the link will simply remain offline and be skipped automatically by "systemd-networkd-wait-online" if "RequiredForOnline=true".

 

[NETWORK] SECTION OPTIONS

The "[Network]" section accepts the following keys:

Description=

A description of the device. This is only used for presentation purposes.

DHCP=

Enables DHCPv4 and/or DHCPv6 client support. Accepts "yes", "no", "ipv4", or "ipv6". Defaults to "no".

Note that DHCPv6 will by default be triggered by Router Advertisement, if that is enabled, regardless of this parameter. By enabling DHCPv6 support explicitly, the DHCPv6 client will be started regardless of the presence of routers on the link, or what flags the routers pass. See "IPv6AcceptRA=".

Furthermore, note that by default the domain name specified through DHCP, on Ubuntu, are used for name resolution. See option UseDomains= below.

See the "[DHCP]" section below for further configuration options for the DHCP client support.

DHCPServer=

A boolean. Enables DHCPv4 server support. Defaults to "no". Further settings for the DHCP server may be set in the "[DHCPServer]" section described below.

LinkLocalAddressing=

Enables link-local address autoconfiguration. Accepts "yes", "no", "ipv4", or "ipv6". Defaults to "ipv6".

IPv4LLRoute=

A boolean. When true, sets up the route needed for non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults to false.

IPv6Token=

An IPv6 address with the top 64 bits unset. When set, indicates the 64-bit interface part of SLAAC IPv6 addresses for this link. Note that the token is only ever used for SLAAC, and not for DHCPv6 addresses, even in the case DHCP is requested by router advertisement. By default, the token is autogenerated.

LLMNR=

A boolean or "resolve". When true, enables m[blue]Link-Local Multicast Name Resolutionm[][1] on the link. When set to "resolve", only resolution is enabled, but not host registration and announcement. Defaults to true. This setting is read by systemd-resolved.service(8).

MulticastDNS=

A boolean or "resolve". When true, enables m[blue]Multicast DNSm[][2] support on the link. When set to "resolve", only resolution is enabled, but not host or service registration and announcement. Defaults to false. This setting is read by systemd-resolved.service(8).

DNSSEC=

A boolean or "allow-downgrade". When true, enables m[blue]DNSSECm[][3] DNS validation support on the link. When set to "allow-downgrade", compatibility with non-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case. This option defines a per-interface setting for resolved.conf(5)'s global DNSSEC= option. Defaults to false. This setting is read by systemd-resolved.service(8).

DNSSECNegativeTrustAnchors=

A space-separated list of DNSSEC negative trust anchor domains. If specified and DNSSEC is enabled, look-ups done via the interface's DNS server will be subject to the list of negative trust anchors, and not require authentication for the specified domains, or anything below it. Use this to disable DNSSEC authentication for specific private domains, that cannot be proven valid using the Internet DNS hierarchy. Defaults to the empty list. This setting is read by systemd-resolved.service(8).

LLDP=

Controls support for Ethernet LLDP packet reception. LLDP is a link-layer protocol commonly implemented on professional routers and bridges which announces which physical port a system is connected to, as well as other related data. Accepts a boolean or the special value "routers-only". When true, incoming LLDP packets are accepted and a database of all LLDP neighbors maintained. If "routers-only" is set only LLDP data of various types of routers is collected and LLDP data about other types of devices ignored (such as stations, telephones and others). If false, LLDP reception is disabled. Defaults to "routers-only". Use networkctl(1) to query the collected neighbor data. LLDP is only available on Ethernet links. See EmitLLDP= below for enabling LLDP packet emission from the local system.

EmitLLDP=

Controls support for Ethernet LLDP packet emission. Accepts a boolean parameter or the special values "nearest-bridge", "non-tpmr-bridge" and "customer-bridge". Defaults to false, which turns off LLDP packet emission. If not false, a short LLDP packet with information about the local system is sent out in regular intervals on the link. The LLDP packet will contain information about the local host name, the local machine ID (as stored in machine-id(5)) and the local interface name, as well as the pretty hostname of the system (as set in machine-info(5)). LLDP emission is only available on Ethernet links. Note that this setting passes data suitable for identification of host to the network and should thus not be enabled on untrusted networks, where such identification data should not be made available. Use this option to permit other systems to identify on which interfaces they are connected to this system. The three special values control propagation of the LLDP packets. The "nearest-bridge" setting permits propagation only to the nearest connected bridge, "non-tpmr-bridge" permits propagation across Two-Port MAC Relays, but not any other bridges, and "customer-bridge" permits propagation until a customer bridge is reached. For details about these concepts, see m[blue]IEEE 802.1AB-2009m[][4]. Note that configuring this setting to true is equivalent to "nearest-bridge", the recommended and most restricted level of propagation. See LLDP= above for an option to enable LLDP reception.

BindCarrier=

A link name or a list of link names. When set, controls the behavior of the current link. When all links in the list are in an operational down state, the current link is brought down. When at least one link has carrier, the current interface is brought up.

Address=

A static IPv4 or IPv6 address and its prefix length, separated by a "/" character. Specify this key more than once to configure several addresses. The format of the address must be as described in inet_pton(3). This is a short-hand for an [Address] section only containing an Address key (see below). This option may be specified more than once.

If the specified address is 0.0.0.0 (for IPv4) or [::] (for IPv6), a new address range of the requested size is automatically allocated from a system-wide pool of unused ranges. The allocated range is checked against all current network interfaces and all known network configuration files to avoid address range conflicts. The default system-wide pool consists of 192.168.0.0/16, 172.16.0.0/12 and 10.0.0.0/8 for IPv4, and fc00::/7 for IPv6. This functionality is useful to manage a large number of dynamically created network interfaces with the same network configuration and automatic address range assignment.

Gateway=

The gateway address, which must be in the format described in inet_pton(3). This is a short-hand for a [Route] section only containing a Gateway key. This option may be specified more than once.

DNS=

A DNS server address, which must be in the format described in inet_pton(3). This option may be specified more than once. This setting is read by systemd-resolved.service(8).

Domains=

A list of domains which should be resolved using the DNS servers on this link. Each item in the list should be a domain name, optionally prefixed with a tilde ("~"). The domains with the prefix are called "routing-only domains". The domains without the prefix are called "search domains" and are first used as search suffixes for extending single-label host names (host names containing no dots) to become fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, each of the specified search domains are appended to it in turn, converting it into a fully qualified domain name, until one of them may be successfully resolved.

Both "search" and "routing-only" domains are used for routing of DNS queries: look-ups for host names ending in those domains (hence also single label names, if any "search domains" are listed), are routed to the DNS servers configured for this interface. The domain routing logic is particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each interface.

The "routing-only" domain "~." (the tilde indicating definition of a routing domain, the dot referring to the DNS root domain which is the implied suffix of all valid DNS names) has special effect. It causes all DNS traffic which does not match another configured domain routing entry to be routed to DNS servers specified for this interface. This setting is useful to prefer a certain set of DNS servers if a link on which they are connected is available.

This setting is read by systemd-resolved.service(8). "Search domains" correspond to the domain and search entries in resolv.conf(5). Domain name routing has no equivalent in the traditional glibc API, which has no concept of domain name servers limited to a specific link.

NTP=

An NTP server address. This option may be specified more than once. This setting is read by systemd-timesyncd.service(8).

IPForward=

Configures IP packet forwarding for the system. If enabled, incoming packets on any network interface will be forwarded to any other interfaces according to the routing table. Takes either a boolean argument, or the values "ipv4" or "ipv6", which only enable IP packet forwarding for the specified address family. This controls the net.ipv4.ip_forward and net.ipv6.conf.all.forwarding sysctl options of the network interface (see m[blue]ip-sysctl.txtm[][5] for details about sysctl options). Defaults to "no".

Note: this setting controls a global kernel option, and does so one way only: if a network that has this setting enabled is set up the global setting is turned on. However, it is never turned off again, even after all networks with this setting enabled are shut down again.

To allow IP packet forwarding only between specific network interfaces use a firewall.

IPMasquerade=

Configures IP masquerading for the network interface. If enabled, packets forwarded from the network interface will be appear as coming from the local host. Takes a boolean argument. Implies IPForward=ipv4. Defaults to "no".

IPv6PrivacyExtensions=

Configures use of stateless temporary addresses that change over time (see m[blue]RFC 4941m[][6], Privacy Extensions for Stateless Address Autoconfiguration in IPv6). Takes a boolean or the special values "prefer-public" and "kernel". When true, enables the privacy extensions and prefers temporary addresses over public addresses. When "prefer-public", enables the privacy extensions, but prefers public addresses over temporary addresses. When false, the privacy extensions remain disabled. When "kernel", the kernel's default setting will be left in place. Defaults to "no".

IPv6AcceptRA=

Enable or disable IPv6 Router Advertisement (RA) reception support for the interface. Takes a boolean parameter. If true, RAs are accepted; if false, RAs are ignored, independently of the local forwarding state. When not set, the kernel default is used, and RAs are accepted only when local forwarding is disabled for that interface. When RAs are accepted, they may trigger the start of the DHCPv6 client if the relevant flags are set in the RA data, or if no routers are found on the link.

Further settings for the IPv6 RA support may be configured in the "[IPv6AcceptRA]" section, see below.

Also see m[blue]ip-sysctl.txtm[][5] in the kernel documentation regarding "accept_ra", but note that systemd's setting of 1 (i.e. true) corresponds to kernel's setting of 2.

IPv6DuplicateAddressDetection=

Configures the amount of IPv6 Duplicate Address Detection (DAD) probes to send. Defaults to unset.

IPv6HopLimit=

Configures IPv6 Hop Limit. For each router that forwards the packet, the hop limit is decremented by 1. When the hop limit field reaches zero, the packet is discarded. Defaults to unset.

IPv4ProxyARP=

A boolean. Configures proxy ARP for IPv4. Proxy ARP is the technique in which one host, usually a router, answers ARP requests intended for another machine. By "faking" its identity, the router accepts responsibility for routing packets to the "real" destination. (see m[blue]RFC 1027m[][7]. Defaults to unset.

IPv6ProxyNDP=

A boolean. Configures proxy NDP for IPv6. Proxy NDP (Neighbor Discovery Protocol) is a technique for IPv6 to allow routing of addresses to a different destination when peers expect them to be present on a certain physical link. In this case a router answers Neighbour Advertisement messages intended for another machine by offering its own MAC address as destination. Unlike proxy ARP for IPv4, it is not enabled globally, but will only send Neighbour Advertisement messages for addresses in the IPv6 neighbor proxy table, which can also be shown by ip -6 neighbour show proxy. systemd-networkd will control the per-interface `proxy_ndp` switch for each configured interface depending on this option. Defautls to unset.

IPv6ProxyNDPAddress=

An IPv6 address, for which Neighbour Advertisement messages will be proxied. This option may be specified more than once. systemd-networkd will add the IPv6ProxyNDPAddress= entries to the kernel's IPv6 neighbor proxy table. This option implies IPv6ProxyNDP=true but has no effect if IPv6ProxyNDP has been set to false. Defaults to unset.

IPv6PrefixDelegation=

Whether to enable or disable Router Advertisement sending on a link. Allowed values are "static" which distributes prefixes as defined in the "[IPv6PrefixDelegation]" and any "[IPv6Prefix]" sections, "dhcpv6" which requests prefixes using a DHCPv6 client configured for another link and any values configured in the "[IPv6PrefixDelegation]" section while ignoring all static prefix configuration sections, "yes" which uses both static configuration and DHCPv6, and "false" which turns off IPv6 prefix delegation altogether. Defaults to "false". See the "[IPv6PrefixDelegation]" and the "[IPv6Prefix]" sections for more configuration options.

IPv6MTUBytes=

Configures IPv6 maximum transmission unit (MTU). An integer greater than or equal to 1280 bytes. Defaults to unset.

Bridge=

The name of the bridge to add the link to. See systemd.netdev(5).

Bond=

The name of the bond to add the link to. See systemd.netdev(5).

VRF=

The name of the VRF to add the link to. See systemd.netdev(5).

VLAN=

The name of a VLAN to create on the link. See systemd.netdev(5). This option may be specified more than once.

MACVLAN=

The name of a MACVLAN to create on the link. See systemd.netdev(5). This option may be specified more than once.

VXLAN=

The name of a VXLAN to create on the link. See systemd.netdev(5). This option may be specified more than once.

Tunnel=

The name of a Tunnel to create on the link. See systemd.netdev(5). This option may be specified more than once.

ActiveSlave=

A boolean. Specifies the new active slave. The "ActiveSlave=" option is only valid for following modes: "active-backup", "balance-alb" and "balance-tlb". Defaults to false.

PrimarySlave=

A boolean. Specifies which slave is the primary device. The specified device will always be the active slave while it is available. Only when the primary is off-line will alternate devices be used. This is useful when one slave is preferred over another, e.g. when one slave has higher throughput than another. The "PrimarySlave=" option is only valid for following modes: "active-backup", "balance-alb" and "balance-tlb". Defaults to false.

ConfigureWithoutCarrier=

A boolean. Allows networkd to configure a specific link even if it has no carrier. Defaults to false.

IgnoreCarrierLoss=

Takes a boolean. Allows networkd to retain both the static and dynamic configuration of the interface even if its carrier is lost. When unset, the value specified with ConfigureWithoutCarrier= is used.
 

[ADDRESS] SECTION OPTIONS

An "[Address]" section accepts the following keys. Specify several "[Address]" sections to configure several addresses.

Address=

As in the "[Network]" section. This key is mandatory.

Peer=

The peer address in a point-to-point connection. Accepts the same format as the "Address" key.

Broadcast=

The broadcast address, which must be in the format described in inet_pton(3). This key only applies to IPv4 addresses. If it is not given, it is derived from the "Address" key.

Label=

An address label.

PreferredLifetime=

Allows the default "preferred lifetime" of the address to be overridden. Only three settings are accepted: "forever" or "infinity" which is the default and means that the address never expires, and "0" which means that the address is considered immediately "expired" and will not be used, unless explicitly requested. A setting of PreferredLifetime=0 is useful for addresses which are added to be used only by a specific application, which is then configured to use them explicitly.

Scope=

The scope of the address, which can be "global", "link" or "host" or an unsigned integer ranges 0 to 255. Defaults to "global".

HomeAddress=

Takes a boolean argument. Designates this address the "home address" as defined in m[blue]RFC 6275m[][8]. Supported only on IPv6. Defaults to false.

DuplicateAddressDetection=

Takes a boolean argument. Do not perform Duplicate Address Detection m[blue]RFC 4862m[][9] when adding this address. Supported only on IPv6. Defaults to false.

ManageTemporaryAddress=

Takes a boolean argument. If true the kernel manage temporary addresses created from this one as template on behalf of Privacy Extensions m[blue]RFC 3041m[][10]. For this to become active, the use_tempaddr sysctl setting has to be set to a value greater than zero. The given address needs to have a prefix length of 64. This flag allows to use privacy extensions in a manually configured network, just like if stateless auto-configuration was active. Defaults to false.

PrefixRoute=

Takes a boolean argument. When adding or modifying an IPv6 address, the userspace application needs a way to suppress adding a prefix route. This is for example relevant together with IFA_F_MANAGERTEMPADDR, where userspace creates autoconf generated addresses, but depending on on-link, no route for the prefix should be added. Defaults to false.

AutoJoin=

Takes a boolean argument. Joining multicast group on ethernet level via ip maddr command would not work if we have an Ethernet switch that does IGMP snooping since the switch would not replicate multicast packets on ports that did not have IGMP reports for the multicast addresses. Linux vxlan interfaces created via ip link add vxlan or networkd's netdev kind vxlan have the group option that enables then to do the required join. By extending ip address command with option "autojoin" we can get similar functionality for openvswitch (OVS) vxlan interfaces as well as other tunneling mechanisms that need to receive multicast traffic. Defaults to "no".
 

[IPV6ADDRESSLABEL] SECTION OPTIONS

An "[IPv6AddressLabel]" section accepts the following keys. Specify several "[IPv6AddressLabel]" sections to configure several address labels. IPv6 address labels are used for address selection. See m[blue]RFC 3484m[][11]. Precedence is managed by userspace, and only the label itself is stored in the kernel

Label=

The label for the prefix (an unsigned integer) ranges 0 to 4294967294. 0xffffffff is reserved. This key is mandatory.

Prefix=

IPv6 prefix is an address with a prefix length, separated by a slash "/" character. This key is mandatory.
 

[ROUTINGPOLICYRULE] SECTION OPTIONS

An "[RoutingPolicyRule]" section accepts the following keys. Specify several "[RoutingPolicyRule]" sections to configure several rules.

TypeOfService=

Specifies the type of service to match a number between 0 to 255.

From=

Specifies the source address prefix to match. Possibly followed by a slash and the prefix length.

To=

Specifies the destination address prefix to match. Possibly followed by a slash and the prefix length.

FirewallMark=

Specifies the iptables firewall mark value to match (a number between 1 and 4294967295).

Table=

Specifies the routing table identifier to lookup if the rule selector matches. The table identifier for a route (a number between 1 and 4294967295).

Priority=

Specifies the priority of this rule. Priority= is an unsigned integer. Higher number means lower priority, and rules get processed in order of increasing number.

IncomingInterface=

Specifies incoming device to match. If the interface is loopback, the rule only matches packets originating from this host.

OutgoingInterface=

Specifies the outgoing device to match. The outgoing interface is only available for packets originating from local sockets that are bound to a device.
 

[ROUTE] SECTION OPTIONS

The "[Route]" section accepts the following keys. Specify several "[Route]" sections to configure several routes.

Gateway=

As in the "[Network]" section.

GatewayOnlink=

The "GatewayOnlink" option tells the kernel that it does not have to check if the gateway is reachable directly by the current machine (i.e., the kernel does not need to check if the gateway is attached to the local network), so that we can insert the route in the kernel table without it being complained about. A boolean, defaults to "no".

Destination=

The destination prefix of the route. Possibly followed by a slash and the prefix length. If omitted, a full-length host route is assumed.

Source=

The source prefix of the route. Possibly followed by a slash and the prefix length. If omitted, a full-length host route is assumed.

Metric=

The metric of the route (an unsigned integer).

IPv6Preference=

Specifies the route preference as defined in m[blue]RFC4191m[][12] for Router Discovery messages. Which can be one of "low" the route has a lowest priority, "medium" the route has a default priority or "high" the route has a highest priority.

Scope=

The scope of the route, which can be "global", "link" or "host". Defaults to "global".

PreferredSource=

The preferred source address of the route. The address must be in the format described in inet_pton(3).

Table=num

The table identifier for the route (a number between 1 and 4294967295, or 0 to unset). The table can be retrieved using ip route show table num.

Protocol=

The Protocol identifier for the route. Takes a number between 0 and 255 or the special values "kernel", "boot" and "static". Defaults to "static".

Type=

The Type identifier for special route types, which can be "unicast" route to a destination network address which describes the path to the destination, "blackhole" packets are discarded silently, "unreachable" packets are discarded and the ICMP message host unreachable is generated, "prohibit" packets are discarded and the ICMP message communication administratively prohibited is generated. Defaults to "unicast".

InitialCongestionWindow=

The TCP initial congestion window is used during the start of a TCP connection. During the start of a TCP session, when a client requests a resource, the server's initial congestion window determines how many data bytes will be sent during the initial burst of data. Takes a size in bytes between 1 and 4294967295 (2^32 - 1). The usual suffixes K, M, G are supported and are understood to the base of 1024. Defaults to unset.

InitialAdvertisedReceiveWindow=

The TCP initial advertised receive window is the amount of receive data (in bytes) that can initally be buffered at one time on a connection. The sending host can send only that amount of data before waiting for an acknowledgment and window update from the receiving host. Takes a size in bytes between 1 and 4294967295 (2^32 - 1). The usual suffixes K, M, G are supported and are understood to the base of 1024. Defaults to unset.

QuickAck=

Takes a boolean argument. When true enables TCP quick ack mode for the route. Defaults to unset.
 

[DHCP] SECTION OPTIONS

The "[DHCP]" section configures the DHCPv4 and DHCP6 client, if it is enabled with the DHCP= setting described above:

UseDNS=

When true (the default), the DNS servers received from the DHCP server will be used and take precedence over any statically configured ones.

This corresponds to the nameserver option in resolv.conf(5).

UseNTP=

When true (the default), the NTP servers received from the DHCP server will be used by systemd-timesyncd and take precedence over any statically configured ones.

UseMTU=

When true, the interface maximum transmission unit from the DHCP server will be used on the current link. If MTUBytes= is set, then this setting is ignored. Defaults to false.

Anonymize=

Takes a boolean argument. When true, the options sent to the DHCP server will follow the m[blue]RFC 7844m[][13] (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information. Defaults to false.

This option should only be set to true when MACAddressPolicy= is set to "random" (see systemd.link(5)).

Note that this configuration will overwrite others. In concrete, the following variables will be ignored: SendHostname=, ClientIdentifier=, UseRoutes=, SendHostname=, UseMTU=, VendorClassIdentifier=, UseTimezone=.

SendHostname=

When true (the default), the machine's hostname will be sent to the DHCP server. Note that the machine's hostname must consist only of 7-bit ASCII lower-case characters and no spaces or dots, and be formatted as a valid DNS domain name. Otherwise, the hostname is not send even if this is set to true.

UseHostname=

When true (the default), the hostname received from the DHCP server will be set as the transient hostname of the system.

Hostname=

Use this value for the hostname which is sent to the DHCP server, instead of machine's hostname. Note that the specified hostname must consist only of 7-bit ASCII lower-case characters and no spaces or dots, and be formatted as a valid DNS domain name.

UseDomains=

Takes a boolean argument, or the special value "route". When true, the domain name received from the DHCP server will be used as DNS search domain over this link, similar to the effect of the Domains= setting. If set to "route", the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching, similar to the effect of the Domains= setting when the argument is prefixed with "~". Defaults to true on Ubuntu.

It is recommended to enable this option only on trusted networks, as setting this affects resolution of all host names, in particular of single-label names. It is generally safer to use the supplied domain only as routing domain, rather than as search domain, in order to not have it affect local resolution of single-label names.

When set to true, this setting corresponds to the domain option in resolv.conf(5).

UseRoutes=

When true (the default), the static routes will be requested from the DHCP server and added to the routing table with a metric of 1024, and a scope of "global", "link" or "host", depending on the route's destination and gateway. If the destination is on the local host, e.g., 127.x.x.x, or the same as the link's own address, the scope will be set to "host". Otherwise if the gateway is null (a direct route), a "link" scope will be used. For anything else, scope defaults to "global".

UseGateway=

When true, the gateway will be requested from the DHCP server and added to the routing table with a metric of 1024, and a scope of "link". When unset, the value specified with UseRoutes= is used.

UseTimezone=

When true, the timezone received from the DHCP server will be set as timezone of the local system. Defaults to "no".

ClientIdentifier=

The DHCPv4 client identifier to use. Either "mac" to use the MAC address of the link or "duid" (the default, see below) to use an RFC4361-compliant Client ID.

VendorClassIdentifier=

The vendor class identifier used to identify vendor type and configuration.

DUIDType=

Override the global DUIDType setting for this network. See networkd.conf(5) for a description of possible values.

DUIDRawData=

Override the global DUIDRawData setting for this network. See networkd.conf(5) for a description of possible values.

IAID=

The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned integer.

RequestBroadcast=

Request the server to use broadcast messages before the IP address has been configured. This is necessary for devices that cannot receive RAW packets, or that cannot receive packets at all before an IP address has been configured. On the other hand, this must not be enabled on networks where broadcasts are filtered out.

RouteMetric=

Set the routing metric for routes specified by the DHCP server.

RouteTable=num

The table identifier for DHCP routes (a number between 1 and 4294967295, or 0 to unset). The table can be retrieved using ip route show table num.

When used in combination with VRF= the VRF's routing table is used unless this parameter is specified.

ListenPort=

Allow setting custom port for the DHCP client to listen on.

RapidCommit=

A boolean. The DHCPv6 client can obtain configuration parameters from a DHCPv6 server through a rapid two-message exchange (solicit and reply). When the rapid commit option is enabled by both the DHCPv6 client and the DHCPv6 server, the two-message exchange is used, rather than the default four-method exchange (solicit, advertise, request, and reply). The two-message exchange provides faster client configuration and is beneficial in environments in which networks are under a heavy load. See m[blue]RFC 3315m[][14] for details. Defaults to true.
 

[IPV6ACCEPTRA] SECTION OPTIONS

The "[IPv6AcceptRA]" section configures the IPv6 Router Advertisement (RA) client, if it is enabled with the IPv6AcceptRA= setting described above:

UseDNS=

When true (the default), the DNS servers received in the Router Advertisement will be used and take precedence over any statically configured ones.

This corresponds to the nameserver option in resolv.conf(5).

UseDomains=

Takes a boolean argument, or the special value "route". When true, the domain name received via IPv6 Router Advertisement (RA) will be used as DNS search domain over this link, similar to the effect of the Domains= setting. If set to "route", the domain name received via IPv6 RA will be used for routing DNS queries only, but not for searching, similar to the effect of the Domains= setting when the argument is prefixed with "~". Defaults to true on Ubuntu.

It is recommended to enable this option only on trusted networks, as setting this affects resolution of all host names, in particular of single-label names. It is generally safer to use the supplied domain only as routing domain, rather than as search domain, in order to not have it affect local resolution of single-label names.

When set to true, this setting corresponds to the domain option in resolv.conf(5).

RouteTable=num

The table identifier for the routes received in the Router Advertisement (a number between 1 and 4294967295, or 0 to unset). The table can be retrieved using ip route show table num.
 

[DHCPSERVER] SECTION OPTIONS

The "[DHCPServer]" section contains settings for the DHCP server, if enabled via the DHCPServer= option described above:

PoolOffset=, PoolSize=

Configures the pool of addresses to hand out. The pool is a contiguous sequence of IP addresses in the subnet configured for the server address, which does not include the subnet nor the broadcast address. PoolOffset= takes the offset of the pool from the start of subnet, or zero to use the default value. PoolSize= takes the number of IP addresses in the pool or zero to use the default value. By default, the pool starts at the first address after the subnet address and takes up the rest of the subnet, excluding the broadcast address. If the pool includes the server address (the default), this is reserved and not handed out to clients.

DefaultLeaseTimeSec=, MaxLeaseTimeSec=

Control the default and maximum DHCP lease time to pass to clients. These settings take time values in seconds or another common time unit, depending on the suffix. The default lease time is used for clients that did not ask for a specific lease time. If a client asks for a lease time longer than the maximum lease time, it is automatically shortened to the specified time. The default lease time defaults to 1h, the maximum lease time to 12h. Shorter lease times are beneficial if the configuration data in DHCP leases changes frequently and clients shall learn the new settings with shorter latencies. Longer lease times reduce the generated DHCP network traffic.

EmitDNS=, DNS=

Configures whether the DHCP leases handed out to clients shall contain DNS server information. The EmitDNS= setting takes a boolean argument and defaults to "yes". The DNS servers to pass to clients may be configured with the DNS= option, which takes a list of IPv4 addresses. If the EmitDNS= option is enabled but no servers configured, the servers are automatically propagated from an "uplink" interface that has appropriate servers set. The "uplink" interface is determined by the default route of the system with the highest priority. Note that this information is acquired at the time the lease is handed out, and does not take uplink interfaces into account that acquire DNS or NTP server information at a later point. DNS server propagation does not take /etc/resolv.conf into account. Also, note that the leases are not refreshed if the uplink network configuration changes. To ensure clients regularly acquire the most current uplink DNS server information, it is thus advisable to shorten the DHCP lease time via MaxLeaseTimeSec= described above.

EmitNTP=, NTP=

Similar to the EmitDNS= and DNS= settings described above, these settings configure whether and what NTP server information shall be emitted as part of the DHCP lease. The same syntax, propagation semantics and defaults apply as for EmitDNS= and DNS=.

EmitRouter=

Similar to the EmitDNS= setting described above, this setting configures whether the DHCP lease should contain the router option. The same syntax, propagation semantics and defaults apply as for EmitDNS=.

EmitTimezone=, Timezone=

Configures whether the DHCP leases handed out to clients shall contain timezone information. The EmitTimezone= setting takes a boolean argument and defaults to "yes". The Timezone= setting takes a timezone string (such as "Europe/Berlin" or "UTC") to pass to clients. If no explicit timezone is set, the system timezone of the local host is propagated, as determined by the /etc/localtime symlink.
 

[IPV6PREFIXDELEGATION] SECTION OPTIONS

The "[IPv6PrefixDelegation]" section contains settings for sending IPv6 Router Advertisements and whether to act as a router, if enabled via the IPv6PrefixDelegation= option described above. IPv6 network prefixes are defined with one or more "[IPv6Prefix]" sections.

Managed=, OtherInformation=

Controls whether a DHCPv6 server is used to acquire IPv6 addresses on the network link when Managed= boolean is set to "true" or if only additional network information can be obtained via DHCPv6 for the network link when OtherInformation= boolean is set to "true". Both settings default to "false", which means that a DHCPv6 server is not being used.

RouterLifetimeSec=

Configures the IPv6 router lifetime in seconds. If set, this host also announces itself in Router Advertisements as an IPv6 router for the network link. Defaults to unset, which means the host is not acting as a router.

RouterPreference=

Configures IPv6 router preference if RouterLifetimeSec= is non-zero. Valid values are "high", "medium" and "low", with "normal" and "default" added as synonyms for "medium" just to make configuration easier. See m[blue]RFC 4191m[][12] for details. Defaults to "medium".

EmitDNS=, DNS=

DNS= specifies a list of recursive DNS server IPv6 addresses that distributed via Router Advertisement messages when EmitDNS= is true. If DNS= is empty, DNS servers are read from the "[Network]" section. If the "[Network]" section does not contain any DNS servers either, DNS servers from the uplink with the highest priority default route are used. When EmitDNS= is false, no DNS server information is sent in Router Advertisement messages. EmitDNS= defaults to true.

EmitDomains=, Domains=

A list of DNS search domains distributed via Router Advertisement messages when EmitDomains= is true. If Domains= is empty, DNS search domains are read from the "[Network]" section. If the "[Network]" section does not contain any DNS search domains either, DNS search domains from the uplink with the highest priority default route are used. When EmitDomains= is false, no DNS search domain information is sent in Router Advertisement messages. EmitDomains= defaults to true.

DNSLifetimeSec=

Lifetime in seconds for the DNS server addresses listed in DNS= and search domains listed in Domains=.
 

[IPV6PREFIX] SECTION OPTIONS

One or more "[IPv6Prefix]" sections contain the IPv6 prefixes that are announced via Router Advertisements. See m[blue]RFC 4861m[][15] for further details.

AddressAutoconfiguration=, OnLink=

Boolean values to specify whether IPv6 addresses can be autoconfigured with this prefix and whether the prefix can be used for onlink determination. Both settings default to "true" in order to ease configuration.

Prefix=

The IPv6 prefix that is to be distributed to hosts. Similarly to configuring static IPv6 addresses, the setting is configured as an IPv6 prefix and its prefix length, separated by a "/" character. Use multiple "[IPv6Prefix]" sections to configure multiple IPv6 prefixes since prefix lifetimes, address autoconfiguration and onlink status may differ from one prefix to another.

PreferredLifetimeSec=, ValidLifetimeSec=

Preferred and valid lifetimes for the prefix measured in seconds. PreferredLifetimeSec= defaults to 604800 seconds (one week) and ValidLifetimeSec= defaults to 2592000 seconds (30 days).
 

[BRIDGE] SECTION OPTIONS

The "[Bridge]" section accepts the following keys.

UnicastFlood=

A boolean. Controls whether the bridge should flood traffic for which an FDB entry is missing and the destination is unknown through this port. Defaults to on.

HairPin=

A boolean. Configures whether traffic may be sent back out of the port on which it was received. By default, this flag is false, and the bridge will not forward traffic back out of the receiving port.

UseBPDU=

A boolean. Configures whether STP Bridge Protocol Data Units will be processed by the bridge port. Defaults to yes.

FastLeave=

A boolean. This flag allows the bridge to immediately stop multicast traffic on a port that receives an IGMP Leave message. It is only used with IGMP snooping if enabled on the bridge. Defaults to off.

AllowPortToBeRoot=

A boolean. Configures whether a given port is allowed to become a root port. Only used when STP is enabled on the bridge. Defaults to on.

Cost=

Sets the "cost" of sending packets of this interface. Each port in a bridge may have a different speed and the cost is used to decide which link to use. Faster interfaces should have lower costs. It is an integer value between 1 and 65535.

Priority=

Sets the "priority" of sending packets on this interface. Each port in a bridge may have a different priority which is used to decide which link to use. Lower value means higher priority. It is an integer value between 0 to 63. Networkd does not set any default, meaning the kernel default value of 32 is used.
 

[BRIDGEFDB] SECTION OPTIONS

The "[BridgeFDB]" section manages the forwarding database table of a port and accepts the following keys. Specify several "[BridgeFDB]" sections to configure several static MAC table entries.

MACAddress=

As in the "[Network]" section. This key is mandatory.

VLANId=

The VLAN ID for the new static MAC table entry. If omitted, no VLAN ID information is appended to the new static MAC table entry.
 

[BRIDGEVLAN] SECTION OPTIONS

The "[BridgeVLAN]" section manages the VLAN ID configuration of a bridge port and accepts the following keys. Specify several "[BridgeVLAN]" sections to configure several VLAN entries. The VLANFiltering= option has to be enabled, see "[Bridge]" section in systemd.netdev(5).

VLAN=

The VLAN ID allowed on the port. This can be either a single ID or a range M-N. VLAN IDs are valid from 1 to 4094.

EgressUntagged=

The VLAN ID specified here will be used to untag frames on egress. Configuring EgressUntagged= implicates the use of VLAN= above and will enable the VLAN ID for ingress as well. This can be either a single ID or a range M-N.

PVID=

The Port VLAN ID specified here is assigned to all untagged frames at ingress. PVID= can be used only once. Configuring PVID= implicates the use of VLAN= above and will enable the VLAN ID for ingress as well.
 

EXAMPLES

Example 1. Static network configuration

# /etc/systemd/network/50-static.network
[Match]
Name=enp2s0

[Network]
Address=192.168.0.15/24
Gateway=192.168.0.1

This brings interface "enp2s0" up with a static address. The specified gateway will be used for a default route.

Example 2. DHCP on ethernet links

# /etc/systemd/network/80-dhcp.network
[Match]
Name=en*

[Network]
DHCP=yes

This will enable DHCPv4 and DHCPv6 on all interfaces with names starting with "en" (i.e. ethernet interfaces).

Example 3. A bridge with two enslaved links

# /etc/systemd/network/25-bridge-static.network
[Match]
Name=bridge0

[Network]
Address=192.168.0.15/24
Gateway=192.168.0.1
DNS=192.168.0.1

# /etc/systemd/network/25-bridge-slave-interface-1.network
[Match]
Name=enp2s0

[Network]
Bridge=bridge0

# /etc/systemd/network/25-bridge-slave-interface-2.network
[Match]
Name=wlp3s0

[Network]
Bridge=bridge0

This creates a bridge and attaches devices "enp2s0" and "wlp3s0" to it. The bridge will have the specified static address and network assigned, and a default route via the specified gateway will be added. The specified DNS server will be added to the global list of DNS resolvers.

Example 4. 

# /etc/systemd/network/20-bridge-slave-interface-vlan.network
[Match]
Name=enp2s0

[Network]
Bridge=bridge0

[BridgeVLAN]
VLAN=1-32
PVID=42
EgressUntagged=42

[BridgeVLAN]
VLAN=100-200

[BridgeVLAN]
EgressUntagged=300-400

This overrides the configuration specified in the previous example for the interface "enp2s0", and enables VLAN on that bridge port. VLAN IDs 1-32, 42, 100-400 will be allowed. Packets tagged with VLAN IDs 42, 300-400 will be untagged when they leave on this interface. Untagged packets which arrive on this interface will be assigned VLAN ID 42.

Example 5. Various tunnels

/etc/systemd/network/25-tunnels.network
[Match]
Name=ens1

[Network]
Tunnel=ipip-tun
Tunnel=sit-tun
Tunnel=gre-tun
Tunnel=vti-tun
      

/etc/systemd/network/25-tunnel-ipip.netdev
[NetDev]
Name=ipip-tun
Kind=ipip
      

/etc/systemd/network/25-tunnel-sit.netdev
[NetDev]
Name=sit-tun
Kind=sit
      

/etc/systemd/network/25-tunnel-gre.netdev
[NetDev]
Name=gre-tun
Kind=gre
      

/etc/systemd/network/25-tunnel-vti.netdev
[NetDev]
Name=vti-tun
Kind=vti
      

This will bring interface "ens1" up and create an IPIP tunnel, a SIT tunnel, a GRE tunnel, and a VTI tunnel using it.

Example 6. A bond device

# /etc/systemd/network/30-bond1.network
[Match]
Name=bond1

[Network]
DHCP=ipv6

# /etc/systemd/network/30-bond1.netdev
[NetDev]
Name=bond1
Kind=bond

# /etc/systemd/network/30-bond1-dev1.network
[Match]
MACAddress=52:54:00:e9:64:41

[Network]
Bond=bond1

# /etc/systemd/network/30-bond1-dev2.network
[Match]
MACAddress=52:54:00:e9:64:42

[Network]
Bond=bond1

This will create a bond device "bond1" and enslave the two devices with MAC addresses 52:54:00:e9:64:41 and 52:54:00:e9:64:42 to it. IPv6 DHCP will be used to acquire an address.

Example 7. Virtual Routing and Forwarding (VRF)

Add the "bond1" interface to the VRF master interface "vrf1". This will redirect routes generated on this interface to be within the routing table defined during VRF creation. For kernels before 4.8 traffic won't be redirected towards the VRFs routing table unless specific ip-rules are added.

# /etc/systemd/network/25-vrf.network
[Match]
Name=bond1

[Network]
VRF=vrf1

Example 8. MacVTap

This brings up a network interface "macvtap-test" and attaches it to "enp0s25".

# /lib/systemd/network/25-macvtap.network
[Match]
Name=enp0s25

[Network]
MACVTAP=macvtap-test
 

SEE ALSO

systemd(1), systemd-networkd.service(8), systemd.link(5), systemd.netdev(5), systemd-resolved.service(8)  

NOTES

1.
Link-Local Multicast Name Resolution
https://tools.ietf.org/html/rfc4795
2.
Multicast DNS
https://tools.ietf.org/html/rfc6762
3.
DNSSEC
https://tools.ietf.org/html/rfc4033
4.
IEEE 802.1AB-2009
http://standards.ieee.org/getieee802/download/802.1AB-2009.pdf
5.
ip-sysctl.txt
https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt
6.
RFC 4941
https://tools.ietf.org/html/rfc4941
7.
RFC 1027
https://tools.ietf.org/html/rfc1027
8.
RFC 6275
https://tools.ietf.org/html/rfc6275
9.
RFC 4862
https://tools.ietf.org/html/rfc4862
10.
RFC 3041
https://tools.ietf.org/html/rfc3041
11.
RFC 3484
https://tools.ietf.org/html/rfc3484
12.
RFC4191
https://tools.ietf.org/html/rfc4191
13.
RFC 7844
https://tools.ietf.org/html/rfc7844
14.
RFC 3315
https://tools.ietf.org/html/rfc3315#section-17.2.1
15.
RFC 4861
https://tools.ietf.org/html/rfc4861


 

Index

NAME
SYNOPSIS
DESCRIPTION
[MATCH] SECTION OPTIONS
[LINK] SECTION OPTIONS
[NETWORK] SECTION OPTIONS
[ADDRESS] SECTION OPTIONS
[IPV6ADDRESSLABEL] SECTION OPTIONS
[ROUTINGPOLICYRULE] SECTION OPTIONS
[ROUTE] SECTION OPTIONS
[DHCP] SECTION OPTIONS
[IPV6ACCEPTRA] SECTION OPTIONS
[DHCPSERVER] SECTION OPTIONS
[IPV6PREFIXDELEGATION] SECTION OPTIONS
[IPV6PREFIX] SECTION OPTIONS
[BRIDGE] SECTION OPTIONS
[BRIDGEFDB] SECTION OPTIONS
[BRIDGEVLAN] SECTION OPTIONS
EXAMPLES
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:56 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.TIME

SYSTEMD.TIME

Section: systemd.time (7)
Updated:
Index Return to Main Contents
 

NAME

systemd.time - Time and date specifications  

DESCRIPTION

In systemd, timestamps, time spans, and calendar events are displayed and may be specified in closely related syntaxes.  

DISPLAYING TIME SPANS

Time spans refer to time durations. On display, systemd will present time spans as a space-separated series of time values each suffixed by a time unit. Example:

2h 30min

All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is locale-independent, only English names for the time units are used.  

PARSING TIME SPANS

When parsing, systemd will accept the same time span syntax. Separating spaces may be omitted. The following time units are understood:

• usec, us

• msec, ms

• seconds, second, sec, s

• minutes, minute, min, m

• hours, hour, hr, h

• days, day, d

• weeks, week, w

• months, month, M (defined as 30.44 days)

• years, year, y (defined as 365.25 days)

If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as such. In a few cases "ns", "nsec" is accepted too, where the granularity of the time span permits this. Parsing is generally locale-independent, non-English names for the time units are not accepted.

Examples for valid time span specifications:

2 h
2hours
48hr
1y 12month
55s500ms
300ms20s 5day
 

DISPLAYING TIMESTAMPS

Timestamps refer to specific, unique points in time. On display, systemd will format these in the local timezone as follows:

Fri 2012-11-23 23:02:15 CET

The weekday is printed in the abbreviated English language form. The formatting is locale-independent.

In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via the "UTC" timezone specifier in the output.

In some cases timestamps are shown with microsecond granularity. In this case the sub-second remainder is separated by a full stop from the seconds component.  

PARSING TIMESTAMPS

When parsing, systemd will accept a similar syntax, but expects no timezone specification, unless it is given as the literal string "UTC" (for the UTC timezone), or is specified to be the locally configured timezone, or the timezone name in the IANA timezone database format. The complete list of timezones supported on your system can be obtained using the "timedatectl list-timezones" (see timedatectl(1)). Using IANA format is recommended over local timezone names, as less prone to errors (eg: with local timezone it's possible to specify daylight saving time in winter, while it's incorrect). The weekday specification is optional, but when the weekday is specified, it must either be in the abbreviated ("Wed") or non-abbreviated ("Wednesday") English language form (case does not matter), and is not subject to the locale choice of the user. Either the date, or the time part may be omitted, in which case the current date or 00:00:00, respectively, is assumed. The seconds component of the time may also be omitted, in which case ":00" is assumed. Year numbers may be specified in full or may be abbreviated (omitting the century).

A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of the week.

When parsing, systemd will also accept a few special placeholders instead of timestamps: "now" may be used to refer to the current time (or of the invocation of the command that is currently executed). "today", "yesterday", and "tomorrow" refer to 00:00:00 of the current day, the day before, or the next day, respectively.

When parsing, systemd will also accept relative time specifications. A time span (see above) that is prefixed with "+" is evaluated to the current time plus the specified time span. Correspondingly, a time span that is prefixed with "-" is evaluated to the current time minus the specified time span. Instead of prefixing the time span with "+" or "-", it may also be suffixed with a space and the word "left" or "ago".

Finally, a timespan prefixed with "@" is evaluated relative to the UNIX time epoch 1st Jan, 1970, 00:00.

Examples for valid timestamps and their normalized form (assuming the current time was 2012-11-23 18:15:22 and the timezone was UTC+8, for example TZ=Asia/Shanghai):

  Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
      2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13
  2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13
               2012-11-23 → Fri 2012-11-23 00:00:00
                 12-11-23 → Fri 2012-11-23 00:00:00
                 11:12:13 → Fri 2012-11-23 11:12:13
                    11:12 → Fri 2012-11-23 11:12:00
                      now → Fri 2012-11-23 18:15:22
                    today → Fri 2012-11-23 00:00:00
                today UTC → Fri 2012-11-23 16:00:00
                yesterday → Fri 2012-11-22 00:00:00
                 tomorrow → Fri 2012-11-24 00:00:00
tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00
                 +3h30min → Fri 2012-11-23 21:45:22
                      -5s → Fri 2012-11-23 18:15:17
                11min ago → Fri 2012-11-23 18:04:22
              @1395716396 → Tue 2014-03-25 03:59:56

Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable locally, as the timezone component is not understood (unless it happens to be "UTC").

Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated by a full stop from the seconds component. Example:

2014-03-25 03:59:56.654563

In some cases, systemd will display a relative timestamp (relative to the current time, or the time of invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative timestamp is formatted as follows:

2 months 5 days ago

Note that a relative timestamp is also accepted where a timestamp is expected (see above).  

CALENDAR EVENTS

Calendar events may be used to refer to one or more points in time in a single expression. They form a superset of the absolute timestamps explained above:

Thu,Fri 2012-*-1,5 11:12:13

The above refers to 11:12:13 of the first or fifth day of any month of the year 2012, but only if that day is a Thursday or Friday.

The weekday specification is optional. If specified, it should consist of one or more English language weekday names, either in the abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not matter), separated by commas. Specifying two weekdays separated by ".." refers to a range of continuous weekdays. "," and ".." may be combined freely.

In the date and time specifications, any component may be specified as "*" in which case any value will match. Alternatively, each component can be specified as a list of values separated by commas. Values may be suffixed with "/" and a repetition value, which indicates that the value itself and the value plus all multiples of the repetition value are matched. Two values separated by ".." may be used to indicate a range of values; ranges may also be followed with "/" and a repetition value.

A date specification may use "~" to indicate the last day(s) in a month. For example, "*-02~03" means "the third last day in February," and "Mon *-05~07/1" means "the last Monday in May."

The seconds component may contain decimal fractions both in the value and the repetition. All fractions are rounded to 6 decimal places.

Either time or date specification may be omitted, in which case the current day and 00:00:00 is implied, respectively. If the second component is not specified, ":00" is assumed.

Timezone can be specified as the literal string "UTC", or the local timezone, similar to the supported syntax of timestamps (see above), or the timezone in the IANA timezone database format (also see above).

The following special expressions may be used as shorthands for longer normalized forms:

    minutely → *-*-* *:*:00
      hourly → *-*-* *:00:00
       daily → *-*-* 00:00:00
     monthly → *-*-01 00:00:00
      weekly → Mon *-*-* 00:00:00
      yearly → *-01-01 00:00:00
   quarterly → *-01,04,07,10-01 00:00:00
semiannually → *-01,07-01 00:00:00
   

Examples for valid timestamps and their normalized form:

  Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00
      Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00
                    Wed *-1 → Wed *-*-01 00:00:00
           Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00
                 Wed, 17:48 → Wed *-*-* 17:48:00
Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03
                *-*-7 0:0:0 → *-*-07 00:00:00
                      10-15 → *-10-15 00:00:00
        monday *-12-* 17:00 → Mon *-12-* 17:00:00
  Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45
       12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00
            12..14:10,20,30 → *-*-* 12..14:10,20,30:00
  mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45
             03-05 08:05:40 → *-03-05 08:05:40
                   08:05:40 → *-*-* 08:05:40
                      05:40 → *-*-* 05:40:00
     Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40
           Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40
           2003-03-05 05:40 → 2003-03-05 05:40:00
 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001
             2003-02..04-05 → 2003-02..04-05 00:00:00
       2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC
                 2003-03-05 → 2003-03-05 00:00:00
                      03-05 → *-03-05 00:00:00
                     hourly → *-*-* *:00:00
                      daily → *-*-* 00:00:00
                  daily UTC → *-*-* 00:00:00 UTC
                    monthly → *-*-01 00:00:00
                     weekly → Mon *-*-* 00:00:00
    weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland
                     yearly → *-01-01 00:00:00
                   annually → *-01-01 00:00:00
                      *:2/3 → *-*-* *:02/3:00

Calendar events are used by timer units, see systemd.timer(5) for details.

Use the calendar command of systemd-analyze(1) to validate and normalize calendar time specifications for testing purposes. The tool also calculates when a specified calendar event would elapse next.  

SEE ALSO

systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5), systemd.directives(7), systemd-analyze(1)


 

Index

NAME
DESCRIPTION
DISPLAYING TIME SPANS
PARSING TIME SPANS
DISPLAYING TIMESTAMPS
PARSING TIMESTAMPS
CALENDAR EVENTS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:56 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.ENVIRONMENT-GENERATOR

SYSTEMD.ENVIRONMENT-GENERATOR

Section: systemd.environment-generator (7)
Updated:
Index Return to Main Contents
 

NAME

systemd.environment-generator - systemd environment file generators  

SYNOPSIS

/lib/systemd/system-environment-generators/some-generator
/usr/lib/systemd/user-environment-generators/some-generator

/run/systemd/system-environment-generators/*
/etc/systemd/system-environment-generators/*
/usr/local/lib/systemd/system-environment-generators/*
/lib/systemd/system-environment-generators/*

/run/systemd/user-environment-generators/*
/etc/systemd/user-environment-generators/*
/usr/local/lib/systemd/user-environment-generators/*
/usr/lib/systemd/user-environment-generators/*

 

DESCRIPTION

Generators are small executables that live in /lib/systemd/system-environment-generators/ and other directories listed above. systemd(1) will execute those binaries very early at the startup of each manager and at configuration reload time, before running the generators described in systemd.generator(7) and before starting any units. Environment generators can override the environment that the manager exports to services and other processes.

Generators are loaded from a set of paths determined during compilation, as listed above. System and user environment generators are loaded from directories with names ending in system-environment-generators/ and user-environment-generators/, respectively. Generators found in directories listed earlier override the ones with the same name in directories lower in the list. A symlink to /dev/null or an empty file can be used to mask a generator, thereby preventing it from running. Please note that the order of the two directories with the highest priority is reversed with respect to the unit load path, and generators in /run overwrite those in /etc.

After installing new generators or updating the configuration, systemctl daemon-reload may be executed. This will re-run all generators, updating environment configuration. It will be used for any services that are started subsequently.

Environment file generators are executed similarly to unit file generators described in systemd.generator(7), with the following differences:

• Generators are executed sequentially in the alphanumerical order of the final component of their name. The output of each generator output is immediately parsed and used to update the environment for generators that run after that. Thus, later generators can use and/or modify the output of earlier generators.

• Generators are run by every manager instance, their output can be different for each user.

It is recommended to use numerical prefixes for generator names to simplify ordering.  

EXAMPLES

Example 1. A simple generator that extends an environment variable if a directory exists in the file system

# 50-xdg-data-dirs.sh

#!/bin/bash

# set the default value
XDG_DATA_DIRS="${XDG_DATA_DIRS:-/usr/local/share/:/usr/share}"

# add a directory if it exists
if [[ -d /opt/foo/share ]]; then
   XDG_DATA_DIRS=/opt/foo/share:${XDG_DATA_DIRS}
fi

# write our output
echo XDG_DATA_DIRS=$XDG_DATA_DIRS

Example 2. A more complicated generator which reads existing configuration and mutates one variable

# 90-rearrange-path.py

#!/usr/bin/env python3

"""

Proof-of-concept systemd environment generator that makes sure that bin dirs
are always after matching sbin dirs in the path.
(Changes /sbin:/bin:/foo/bar to /bin:/sbin:/foo/bar.)

This generator shows how to override the configuration possibly created by
earlier generators. It would be easier to write in bash, but let's have it
in Python just to prove that we can, and to serve as a template for more
interesting generators.

"""

import os
import pathlib

def rearrange_bin_sbin(path):
    """Make sure any pair of .../bin, .../sbin directories is in this order

    >>> rearrange_bin_sbin('/bin:/sbin:/usr/sbin:/usr/bin')
    '/bin:/sbin:/usr/bin:/usr/sbin'
    """
    items = [pathlib.Path(p) for p in path.split(':')]
    for i in range(len(items)):
        if 'sbin' in items[i].parts:
            ind = items[i].parts.index('sbin')
            bin = pathlib.Path(*items[i].parts[:ind], 'bin', *items[i].parts[ind+1:])
            if bin in items[i+1:]:
                j = i + 1 + items[i+1:].index(bin)
                items[i], items[j] = items[j], items[i]
    return ':'.join(p.as_posix() for p in items)

if __name__ == '__main__':
    path = os.environ['PATH'] # This should be always set.
                              # If it's not, we'll just crash, we is OK too.
    new = rearrange_bin_sbin(path)
    if new != path:
        print('PATH={}'.format(new))

Example 3. Debugging a generator

SYSTEMD_LOG_LEVEL=debug VAR_A=something VAR_B="something else" \
/lib/systemd/system-environment-generators/path-to-generator
 

SEE ALSO

systemd-environment-d-generator(8), systemd.generator(7), systemd(1), systemctl(1)


 

Index

NAME
SYNOPSIS
DESCRIPTION
EXAMPLES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:57 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.JOURNAL-FIELDS

SYSTEMD.JOURNAL-FIELDS

Section: systemd.journal-fields (7)
Updated:
Index Return to Main Contents
 

NAME

systemd.journal-fields - Special journal fields  

DESCRIPTION

Entries in the journal resemble an environment block in their syntax but with fields that can include binary data. Primarily, fields are formatted UTF-8 text strings, and binary formatting is used only where formatting as UTF-8 text strings makes little sense. New fields may freely be defined by applications, but a few fields have special meaning. All fields with special meanings are optional. In some cases, fields may appear more than once per entry.  

USER JOURNAL FIELDS

User fields are fields that are directly passed from clients and stored in the journal.

MESSAGE=

The human-readable message string for this entry. This is supposed to be the primary text shown to the user. It is usually not translated (but might be in some cases), and is not supposed to be parsed for metadata.

MESSAGE_ID=

A 128-bit message identifier ID for recognizing certain message types, if this is desirable. This should contain a 128-bit ID formatted as a lower-case hexadecimal string, without any separating dashes or suchlike. This is recommended to be a UUID-compatible ID, but this is not enforced, and formatted differently. Developers can generate a new ID for this purpose with journalctl --new-id128.

PRIORITY=

A priority value between 0 ("emerg") and 7 ("debug") formatted as a decimal string. This field is compatible with syslog's priority concept.

CODE_FILE=, CODE_LINE=, CODE_FUNC=

The code location generating this message, if known. Contains the source filename, the line number and the function name.

ERRNO=

The low-level Unix error number causing this entry, if any. Contains the numeric value of errno(3) formatted as a decimal string.

SYSLOG_FACILITY=, SYSLOG_IDENTIFIER=, SYSLOG_PID=

Syslog compatibility fields containing the facility (formatted as decimal string), the identifier string (i.e. "tag"), and the client PID. (Note that the tag is usually derived from glibc's program_invocation_short_name variable, see program_invocation_short_name(3).)
 

TRUSTED JOURNAL FIELDS

Fields prefixed with an underscore are trusted fields, i.e. fields that are implicitly added by the journal and cannot be altered by client code.

_PID=, _UID=, _GID=

The process, user, and group ID of the process the journal entry originates from formatted as a decimal string. Note that entries obtained via "stdout" or "stderr" of forked processes will contain credentials valid for a parent process (that initiated the connection to systemd-journald).

_COMM=, _EXE=, _CMDLINE=

The name, the executable path, and the command line of the process the journal entry originates from.

_CAP_EFFECTIVE=

The effective capabilities(7) of the process the journal entry originates from.

_AUDIT_SESSION=, _AUDIT_LOGINUID=

The session and login UID of the process the journal entry originates from, as maintained by the kernel audit subsystem.

_SYSTEMD_CGROUP=, _SYSTEMD_SLICE=, _SYSTEMD_UNIT=, _SYSTEMD_USER_UNIT=, _SYSTEMD_SESSION=, _SYSTEMD_OWNER_UID=

The control group path in the systemd hierarchy, the the systemd slice unit name, the systemd unit name, the unit name in the systemd user manager (if any), the systemd session ID (if any), and the owner UID of the systemd user unit or systemd session (if any) of the process the journal entry originates from.

_SELINUX_CONTEXT=

The SELinux security context (label) of the process the journal entry originates from.

_SOURCE_REALTIME_TIMESTAMP=

The earliest trusted timestamp of the message, if any is known that is different from the reception time of the journal. This is the time in microseconds since the epoch UTC, formatted as a decimal string.

_BOOT_ID=

The kernel boot ID for the boot the message was generated in, formatted as a 128-bit hexadecimal string.

_MACHINE_ID=

The machine ID of the originating host, as available in machine-id(5).

_SYSTEMD_INVOCATION_ID=

The invocation ID for the runtime cycle of the unit the message was generated in, as available to processes of the unit in $INVOCATION_ID (see systemd.exec(5)).

_HOSTNAME=

The name of the originating host.

_TRANSPORT=

How the entry was received by the journal service. Valid transports are:

audit

for those read from the kernel audit subsystem

driver

for internally generated messages

syslog

for those received via the local syslog socket with the syslog protocol

journal

for those received via the native journal protocol

stdout

for those read from a service's standard output or error output

kernel

for those read from the kernel

_STREAM_ID=

Only applies to "_TRANSPORT=stdout" records: specifies a randomized 128bit ID assigned to the stream connection when it was first created. This ID is useful to reconstruct individual log streams from the log records: all log records carrying the same stream ID originate from the same stream.

_LINE_BREAK=

Only applies to "_TRANSPORT=stdout" records: indicates that the log message in the standard output/error stream was not terminated with a normal newline character ("\n", i.e. ASCII 10). Specifically, when set this field is one of nul (in case the line was terminated by a NUL byte), line-max (in case the maximum log line length was reached, as configured with LineMax= in journald.conf(5)) or eof (if this was the last log record of a stream and the stream ended without a final newline character). Note that this record is not generated when a normal newline character was used for marking the log line end.
 

KERNEL JOURNAL FIELDS

Kernel fields are fields that are used by messages originating in the kernel and stored in the journal.

_KERNEL_DEVICE=

The kernel device name. If the entry is associated to a block device, the major and minor of the device node, separated by ":" and prefixed by "b". Similar for character devices but prefixed by "c". For network devices, this is the interface index prefixed by "n". For all other devices, this is the subsystem name prefixed by "+", followed by ":", followed by the kernel device name.

_KERNEL_SUBSYSTEM=

The kernel subsystem name.

_UDEV_SYSNAME=

The kernel device name as it shows up in the device tree below /sys.

_UDEV_DEVNODE=

The device node path of this device in /dev.

_UDEV_DEVLINK=

Additional symlink names pointing to the device node in /dev. This field is frequently set more than once per entry.
 

FIELDS TO LOG ON BEHALF OF A DIFFERENT PROGRAM

Fields in this section are used by programs to specify that they are logging on behalf of another program or unit.

Fields used by the systemd-coredump coredump kernel helper:

COREDUMP_UNIT=, COREDUMP_USER_UNIT=

Used to annotate messages containing coredumps from system and session units. See coredumpctl(1).

Privileged programs (currently UID 0) may attach OBJECT_PID= to a message. This will instruct systemd-journald to attach additional fields on behalf of the caller:

OBJECT_PID=PID

PID of the program that this message pertains to.

OBJECT_UID=, OBJECT_GID=, OBJECT_COMM=, OBJECT_EXE=, OBJECT_CMDLINE=, OBJECT_AUDIT_SESSION=, OBJECT_AUDIT_LOGINUID=, OBJECT_SYSTEMD_CGROUP=, OBJECT_SYSTEMD_SESSION=, OBJECT_SYSTEMD_OWNER_UID=, OBJECT_SYSTEMD_UNIT=, OBJECT_SYSTEMD_USER_UNIT=

These are additional fields added automatically by systemd-journald. Their meaning is the same as _UID=, _GID=, _COMM=, _EXE=, _CMDLINE=, _AUDIT_SESSION=, _AUDIT_LOGINUID=, _SYSTEMD_CGROUP=, _SYSTEMD_SESSION=, _SYSTEMD_UNIT=, _SYSTEMD_USER_UNIT=, and _SYSTEMD_OWNER_UID= as described above, except that the process identified by PID is described, instead of the process which logged the message.
 

ADDRESS FIELDS

During serialization into external formats, such as the m[blue]Journal Export Formatm[][1] or the m[blue]Journal JSON Formatm[][2], the addresses of journal entries are serialized into fields prefixed with double underscores. Note that these are not proper fields when stored in the journal but for addressing metadata of entries. They cannot be written as part of structured log entries via calls such as sd_journal_send(3). They may also not be used as matches for sd_journal_add_match(3)

__CURSOR=

The cursor for the entry. A cursor is an opaque text string that uniquely describes the position of an entry in the journal and is portable across machines, platforms and journal files.

__REALTIME_TIMESTAMP=

The wallclock time (CLOCK_REALTIME) at the point in time the entry was received by the journal, in microseconds since the epoch UTC, formatted as a decimal string. This has different properties from "_SOURCE_REALTIME_TIMESTAMP=", as it is usually a bit later but more likely to be monotonic.

__MONOTONIC_TIMESTAMP=

The monotonic time (CLOCK_MONOTONIC) at the point in time the entry was received by the journal in microseconds, formatted as a decimal string. To be useful as an address for the entry, this should be combined with the boot ID in "_BOOT_ID=".
 

SEE ALSO

systemd(1), journalctl(1), journald.conf(5), sd-journal(3), coredumpctl(1), systemd.directives(7)  

NOTES

1.
Journal Export Format
https://www.freedesktop.org/wiki/Software/systemd/export
2.
Journal JSON Format
https://www.freedesktop.org/wiki/Software/systemd/json


 

Index

NAME
DESCRIPTION
USER JOURNAL FIELDS
TRUSTED JOURNAL FIELDS
KERNEL JOURNAL FIELDS
FIELDS TO LOG ON BEHALF OF A DIFFERENT PROGRAM
ADDRESS FIELDS
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:57 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.OFFLINE-UPDATES

SYSTEMD.OFFLINE-UPDATES

Section: systemd.offline-updates (7)
Updated:
Index Return to Main Contents
 

NAME

systemd.offline-updates - Implementation of offline updates in systemd  

IMPLEMENTING OFFLINE SYSTEM UPDATES

This man page describes how to implement "offline" system updates with systemd. By "offline" OS updates we mean package installations and updates that are run with the system booted into a special system update mode, in order to avoid problems related to conflicts of libraries and services that are currently running with those on disk. This document is inspired by this m[blue]GNOME design whiteboardm[][1].

The logic:

1. The package manager prepares system updates by downloading all (RPM or DEB or whatever) packages to update off-line in a special directory /var/lib/system-update (or another directory of the package/upgrade manager's choice).

2. When the user OK'ed the update, the symlink /system-update is created that points to /var/lib/system-update (or wherever the directory with the upgrade files is located) and the system is rebooted. This symlink is in the root directory, since we need to check for it very early at boot, at a time where /var is not available yet.

3. Very early in the new boot systemd-system-update-generator(8) checks whether /system-update exists. If so, it (temporarily and for this boot only) redirects (i.e. symlinks) default.target to system-update.target, a special target that pulls in the base system (i.e. sysinit.target, so that all file systems are mounted but little else) and the system update units.

4. The system now continues to boot into default.target, and thus into system-update.target. This target pulls in all system update units. Only one service should perform an update (see the next point), and all the other ones should exit cleanly with a "success" return code and without doing anything. Update services should be ordered after sysinit.target so that the update starts after all file systems have been mounted.

5. As the first step, an update service should check if the /system-update symlink points to the location used by that update service. In case it does not exist or points to a different location, the service must exit without error. It is possible for multiple update services to be installed, and for multiple update services to be launched in parallel, and only the one that corresponds to the tool that created the symlink before reboot should perform any actions. It is unsafe to run multiple updates in parallel.

6. The update service should now do its job. If applicable and possible, it should create a file system snapshot, then install all packages. After completion (regardless whether the update succeeded or failed) the machine must be rebooted, for example by calling systemctl reboot. In addition, on failure the script should revert to the old file system snapshot (without the symlink).

7. The upgrade scripts should exit only after the update is finished. It is expected that the service which performs the upgrade will cause the machine to reboot after it is done. If the system-update.target is successfully reached, i.e. all update services have run, and the /system-update symlink still exists, it will be removed and the machine rebooted as a safety measure.

8. After a reboot, now that the /system-update symlink is gone, the generator won't redirect default.target anymore and the system now boots into the default target again.
 

RECOMMENDATIONS

1. To make things a bit more robust we recommend hooking the update script into system-update.target via a .wants/ symlink in the distribution package, rather than depending on systemctl enable in the postinst scriptlets of your package. More specifically, for your update script create a .service file, without [Install] section, and then add a symlink like /lib/systemd/system-update.target.wants/foobar.service → ../foobar.service to your package.

2. Make sure to remove the /system-update symlink as early as possible in the update script to avoid reboot loops in case the update fails.

3. Use FailureAction=reboot in the service file for your update script to ensure that a reboot is automatically triggered if the update fails. FailureAction= makes sure that the specified unit is activated if your script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds you should trigger the reboot in your own code, for example by invoking logind's Reboot() call or calling systemctl reboot. See m[blue]logind dbus APIm[][2] for details.

4. The update service should declare DefaultDependencies=false, Requires=sysinit.target, After=sysinit.target, and explicitly pull in any other services it requires.
 

SEE ALSO

systemd(1), systemd.generator(7), systemd-system-update-generator(8), dnf.plugin.system-upgrade(8)  

NOTES

1.
GNOME design whiteboard
https://wiki.gnome.org/Design/OS/SoftwareUpdates
2.
logind dbus API
https://www.freedesktop.org/wiki/Software/systemd/logind


 

Index

NAME
IMPLEMENTING OFFLINE SYSTEM UPDATES
RECOMMENDATIONS
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:57 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.INDEX

SYSTEMD.INDEX

Section: systemd.index (7)
Updated:
Index Return to Main Contents
 

NAME

systemd.index - List all manpages from the systemd project  

3

30-systemd-environment-d-generator(8) --- Load variables specified by

 

B

binfmt.d(5) --- Configure additional binary formats for executables at boot
bootctl(1) --- Control the firmware and boot manager settings
bootup(7) --- System bootup process
busctl(1) --- Introspect the bus

 

C

coredump.conf(5) --- Core dump storage configuration files
coredump.conf.d(5) --- Core dump storage configuration files
coredumpctl(1) --- Retrieve and process saved core dumps and metadata
crypttab(5) --- Configuration for encrypted block devices

 

D

daemon(7) --- Writing and packaging system daemons
dnssec-trust-anchors.d(5) --- DNSSEC trust anchor configuration files

 

E

environment.d(5) --- Definition of user session environment

 

F

file-hierarchy(7) --- File system hierarchy overview

 

H

halt(8) --- Halt, power-off or reboot the machine
hostname(5) --- Local hostname configuration file
hostnamectl(1) --- Control the system hostname
hwdb(7) --- Hardware Database

 

I

init(1) --- systemd system and service manager

 

J

journal-remote.conf(5) --- Configuration files for the service accepting remote journal uploads
journal-remote.conf.d(5) --- Configuration files for the service accepting remote journal uploads
journal-upload.conf(5) --- Configuration files for the journal upload service
journal-upload.conf.d(5) --- Configuration files for the journal upload service
journalctl(1) --- Query the systemd journal
journald.conf(5) --- Journal service configuration files
journald.conf.d(5) --- Journal service configuration files

 

K

kernel-command-line(7) --- Kernel command line parameters
kernel-install(8) --- Add and remove kernel and initramfs images to and from /boot

 

L

libnss_myhostname.so.2(8) --- Provide hostname resolution for the locally configured system hostname.
libnss_mymachines.so.2(8) --- Provide hostname resolution for local container instances.
libnss_resolve.so.2(8) --- Provide hostname resolution via
libnss_systemd.so.2(8) --- Provide UNIX user and group name resolution for dynamic users and groups.
libudev(3) --- API for enumerating and introspecting local devices
locale.conf(5) --- Configuration file for locale settings
localectl(1) --- Control the system locale and keyboard layout settings
localtime(5) --- Local timezone configuration file
loginctl(1) --- Control the systemd login manager
logind.conf(5) --- Login manager configuration files
logind.conf.d(5) --- Login manager configuration files

 

M

machine-id(5) --- Local machine ID configuration file
machine-info(5) --- Local machine information file
machinectl(1) --- Control the systemd machine manager
modules-load.d(5) --- Configure kernel modules to load at boot

 

N

networkctl(1) --- Query the status of network links
networkd.conf(5) --- Global Network configuration files
networkd.conf.d(5) --- Global Network configuration files
nss-myhostname(8) --- Provide hostname resolution for the locally configured system hostname.
nss-mymachines(8) --- Provide hostname resolution for local container instances.
nss-resolve(8) --- Provide hostname resolution via
nss-systemd(8) --- Provide UNIX user and group name resolution for dynamic users and groups.

 

O

os-release(5) --- Operating system identification

 

P

pam_systemd(8) --- Register user sessions in the systemd login manager
poweroff(8) --- Halt, power-off or reboot the machine

 

R

reboot(8) --- Halt, power-off or reboot the machine
resolved.conf(5) --- Network Name Resolution configuration files
resolved.conf.d(5) --- Network Name Resolution configuration files
runlevel(8) --- Print previous and current SysV runlevel

 

S

sd-bus(3) --- A lightweight D-Bus IPC client library
sd-bus-errors(3) --- Standard D-Bus error names
sd-daemon(3) --- APIs for new-style daemons
sd-event(3) --- A generic event loop implementation
sd-id128(3) --- APIs for processing 128-bit IDs
sd-journal(3) --- APIs for submitting and querying log entries to and from the journal
sd-login(3) --- APIs for tracking logins
SD_ALERT(3) --- APIs for new-style daemons
sd_booted(3) --- Test whether the system is running the systemd init system
sd_bus_add_match(3) --- Add a match rule for incoming message dispatching
sd_bus_add_match_async(3) --- Add a match rule for incoming message dispatching
sd_bus_creds_get_audit_login_uid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_audit_session_id(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_augmented_mask(3) --- Retrieve credentials object for the specified PID
sd_bus_creds_get_cgroup(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_cmdline(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_comm(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_description(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_egid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_euid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_exe(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_fsgid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_fsuid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_gid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_mask(3) --- Retrieve credentials object for the specified PID
sd_bus_creds_get_owner_uid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_pid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_ppid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_selinux_context(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_session(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_sgid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_slice(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_suid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_supplementary_gids(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_tid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_tid_comm(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_tty(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_uid(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_unique_name(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_unit(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_user_slice(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_user_unit(3) --- Retrieve fields from a credentials object
sd_bus_creds_get_well_known_names(3) --- Retrieve fields from a credentials object
sd_bus_creds_has_bounding_cap(3) --- Retrieve fields from a credentials object
sd_bus_creds_has_effective_cap(3) --- Retrieve fields from a credentials object
sd_bus_creds_has_inheritable_cap(3) --- Retrieve fields from a credentials object
sd_bus_creds_has_permitted_cap(3) --- Retrieve fields from a credentials object
sd_bus_creds_new_from_pid(3) --- Retrieve credentials object for the specified PID
sd_bus_creds_ref(3) --- Retrieve credentials object for the specified PID
sd_bus_creds_unref(3) --- Retrieve credentials object for the specified PID
sd_bus_creds_unrefp(3) --- Retrieve credentials object for the specified PID
sd_bus_default(3) --- Acquire a connection to a system or user bus
sd_bus_default_system(3) --- Acquire a connection to a system or user bus
sd_bus_default_user(3) --- Acquire a connection to a system or user bus
sd_bus_error(3) --- sd-bus error handling
SD_BUS_ERROR_ACCESS_DENIED(3) --- Standard D-Bus error names
sd_bus_error_add_map(3) --- Additional sd-dbus error mappings
SD_BUS_ERROR_ADDRESS_IN_USE(3) --- Standard D-Bus error names
SD_BUS_ERROR_AUTH_FAILED(3) --- Standard D-Bus error names
SD_BUS_ERROR_BAD_ADDRESS(3) --- Standard D-Bus error names
sd_bus_error_copy(3) --- sd-bus error handling
SD_BUS_ERROR_DISCONNECTED(3) --- Standard D-Bus error names
SD_BUS_ERROR_END(3) --- Additional sd-dbus error mappings
SD_BUS_ERROR_FAILED(3) --- Standard D-Bus error names
SD_BUS_ERROR_FILE_EXISTS(3) --- Standard D-Bus error names
SD_BUS_ERROR_FILE_NOT_FOUND(3) --- Standard D-Bus error names
sd_bus_error_free(3) --- sd-bus error handling
sd_bus_error_get_errno(3) --- sd-bus error handling
sd_bus_error_has_name(3) --- sd-bus error handling
SD_BUS_ERROR_INCONSISTENT_MESSAGE(3) --- Standard D-Bus error names
SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED(3) --- Standard D-Bus error names
SD_BUS_ERROR_INVALID_ARGS(3) --- Standard D-Bus error names
SD_BUS_ERROR_INVALID_SIGNATURE(3) --- Standard D-Bus error names
SD_BUS_ERROR_IO_ERROR(3) --- Standard D-Bus error names
sd_bus_error_is_set(3) --- sd-bus error handling
SD_BUS_ERROR_LIMITS_EXCEEDED(3) --- Standard D-Bus error names
SD_BUS_ERROR_MAKE_CONST(3) --- sd-bus error handling
sd_bus_error_map(3) --- Additional sd-dbus error mappings
SD_BUS_ERROR_MAP(3) --- Additional sd-dbus error mappings
SD_BUS_ERROR_MATCH_RULE_INVALID(3) --- Standard D-Bus error names
SD_BUS_ERROR_MATCH_RULE_NOT_FOUND(3) --- Standard D-Bus error names
SD_BUS_ERROR_NAME_HAS_NO_OWNER(3) --- Standard D-Bus error names
SD_BUS_ERROR_NO_MEMORY(3) --- Standard D-Bus error names
SD_BUS_ERROR_NO_NETWORK(3) --- Standard D-Bus error names
SD_BUS_ERROR_NO_REPLY(3) --- Standard D-Bus error names
SD_BUS_ERROR_NO_SERVER(3) --- Standard D-Bus error names
SD_BUS_ERROR_NOT_SUPPORTED(3) --- Standard D-Bus error names
SD_BUS_ERROR_NULL(3) --- sd-bus error handling
SD_BUS_ERROR_PROPERTY_READ_ONLY(3) --- Standard D-Bus error names
SD_BUS_ERROR_SERVICE_UNKNOWN(3) --- Standard D-Bus error names
sd_bus_error_set(3) --- sd-bus error handling
sd_bus_error_set_const(3) --- sd-bus error handling
sd_bus_error_set_errno(3) --- sd-bus error handling
sd_bus_error_set_errnof(3) --- sd-bus error handling
sd_bus_error_set_errnofv(3) --- sd-bus error handling
sd_bus_error_setf(3) --- sd-bus error handling
SD_BUS_ERROR_TIMEOUT(3) --- Standard D-Bus error names
SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN(3) --- Standard D-Bus error names
SD_BUS_ERROR_UNKNOWN_INTERFACE(3) --- Standard D-Bus error names
SD_BUS_ERROR_UNKNOWN_METHOD(3) --- Standard D-Bus error names
SD_BUS_ERROR_UNKNOWN_OBJECT(3) --- Standard D-Bus error names
SD_BUS_ERROR_UNKNOWN_PROPERTY(3) --- Standard D-Bus error names
sd_bus_get_connected_signal(3) --- Control emmission of local connection establishment signal on bus connections
sd_bus_get_fd(3) --- Get the file descriptor connected to the message bus
sd_bus_get_sender(3) --- Configure default sender for outgoing messages
sd_bus_get_watch_bind(3) --- Control socket binding watching on bus connections
sd_bus_is_open(3) --- Check whether the a bus connection is open or ready.
sd_bus_is_ready(3) --- Check whether the a bus connection is open or ready.
sd_bus_match_signal(3) --- Add a match rule for incoming message dispatching
sd_bus_match_signal_async(3) --- Add a match rule for incoming message dispatching
sd_bus_message_append(3) --- Attach fields to a D-Bus message based on a type string
sd_bus_message_append_array(3) --- Append an array of fields to a D-Bus message
sd_bus_message_append_array_iovec(3) --- Append an array of fields to a D-Bus message
sd_bus_message_append_array_memfd(3) --- Append an array of fields to a D-Bus message
sd_bus_message_append_array_space(3) --- Append an array of fields to a D-Bus message
sd_bus_message_append_basic(3) --- Attach a single field to a message
sd_bus_message_append_string_iovec(3) --- Attach a string to a message
sd_bus_message_append_string_memfd(3) --- Attach a string to a message
sd_bus_message_append_string_space(3) --- Attach a string to a message
sd_bus_message_append_strv(3) --- Attach an array of strings to a message
sd_bus_message_appendv(3) --- Attach fields to a D-Bus message based on a type string
sd_bus_message_get_cookie(3) --- Returns the transaction cookie of a message
sd_bus_message_get_monotonic_usec(3) --- Retrieve the sender timestamps and sequence number of a message
sd_bus_message_get_realtime_usec(3) --- Retrieve the sender timestamps and sequence number of a message
sd_bus_message_get_reply_cookie(3) --- Returns the transaction cookie of a message
sd_bus_message_get_seqnum(3) --- Retrieve the sender timestamps and sequence number of a message
sd_bus_message_read_basic(3) --- Read a basic type from a message
sd_bus_message_set_destination(3) --- Set the destination or sender service name of a bus message
sd_bus_message_set_sender(3) --- Set the destination or sender service name of a bus message
sd_bus_negotiate_creds(3) --- Control feature negotiation on bus connections
sd_bus_negotiate_fds(3) --- Control feature negotiation on bus connections
sd_bus_negotiate_timestamp(3) --- Control feature negotiation on bus connections
sd_bus_new(3) --- Create a new bus object and create or destroy references to it
sd_bus_open(3) --- Acquire a connection to a system or user bus
sd_bus_open_system(3) --- Acquire a connection to a system or user bus
sd_bus_open_system_machine(3) --- Acquire a connection to a system or user bus
sd_bus_open_system_remote(3) --- Acquire a connection to a system or user bus
sd_bus_open_user(3) --- Acquire a connection to a system or user bus
sd_bus_path_decode(3) --- Convert an external identifier into an object path and back
sd_bus_path_decode_many(3) --- Convert an external identifier into an object path and back
sd_bus_path_encode(3) --- Convert an external identifier into an object path and back
sd_bus_path_encode_many(3) --- Convert an external identifier into an object path and back
sd_bus_process(3) --- Drive the connection
sd_bus_ref(3) --- Create a new bus object and create or destroy references to it
sd_bus_release_name(3) --- Request or release a well-known service name on a bus
sd_bus_release_name_async(3) --- Request or release a well-known service name on a bus
sd_bus_request_name(3) --- Request or release a well-known service name on a bus
sd_bus_request_name_async(3) --- Request or release a well-known service name on a bus
sd_bus_set_connected_signal(3) --- Control emmission of local connection establishment signal on bus connections
sd_bus_set_sender(3) --- Configure default sender for outgoing messages
sd_bus_set_watch_bind(3) --- Control socket binding watching on bus connections
sd_bus_track_add_name(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_add_sender(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_contains(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_count(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_count_name(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_count_sender(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_first(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_get_bus(3) --- Track bus peers
sd_bus_track_get_recursive(3) --- Track bus peers
sd_bus_track_get_userdata(3) --- Track bus peers
sd_bus_track_new(3) --- Track bus peers
sd_bus_track_next(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_ref(3) --- Track bus peers
sd_bus_track_remove_name(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_remove_sender(3) --- Add, remove and retrieve bus peers tracked in a bus peer tracking object
sd_bus_track_set_recursive(3) --- Track bus peers
sd_bus_track_set_userdata(3) --- Track bus peers
sd_bus_track_unref(3) --- Track bus peers
sd_bus_track_unrefp(3) --- Track bus peers
sd_bus_unref(3) --- Create a new bus object and create or destroy references to it
sd_bus_unrefp(3) --- Create a new bus object and create or destroy references to it
SD_CRIT(3) --- APIs for new-style daemons
SD_DEBUG(3) --- APIs for new-style daemons
SD_EMERG(3) --- APIs for new-style daemons
SD_ERR(3) --- APIs for new-style daemons
sd_event(3) --- Acquire and release an event loop object
sd_event_add_child(3) --- Add a child process state change event source to an event loop
sd_event_add_defer(3) --- Add static event sources to an event loop
sd_event_add_exit(3) --- Add static event sources to an event loop
sd_event_add_io(3) --- Add an I/O event source to an event loop
sd_event_add_post(3) --- Add static event sources to an event loop
sd_event_add_signal(3) --- Add a UNIX process signal event source to an event loop
sd_event_add_time(3) --- Add a timer event source to an event loop
SD_EVENT_ARMED(3) --- Low-level event loop operations
sd_event_child_handler_t(3) --- Add a child process state change event source to an event loop
sd_event_default(3) --- Acquire and release an event loop object
sd_event_dispatch(3) --- Low-level event loop operations
sd_event_exit(3) --- Ask the event loop to exit
SD_EVENT_EXITING(3) --- Low-level event loop operations
SD_EVENT_FINISHED(3) --- Low-level event loop operations
sd_event_get_exit_code(3) --- Ask the event loop to exit
sd_event_get_fd(3) --- Obtain a file descriptor to poll for event loop events
sd_event_get_iteration(3) --- Low-level event loop operations
sd_event_get_state(3) --- Low-level event loop operations
sd_event_get_tid(3) --- Acquire and release an event loop object
sd_event_get_watchdog(3) --- Enable event loop watchdog support
sd_event_handler_t(3) --- Add static event sources to an event loop
SD_EVENT_INITIAL(3) --- Low-level event loop operations
sd_event_io_handler_t(3) --- Add an I/O event source to an event loop
sd_event_loop(3) --- Run an event loop
sd_event_new(3) --- Acquire and release an event loop object
sd_event_now(3) --- Retrieve current event loop iteration timestamp
SD_EVENT_OFF(3) --- Enable or disable event sources
SD_EVENT_ON(3) --- Enable or disable event sources
SD_EVENT_ONESHOT(3) --- Enable or disable event sources
SD_EVENT_PENDING(3) --- Low-level event loop operations
sd_event_prepare(3) --- Low-level event loop operations
SD_EVENT_PREPARING(3) --- Low-level event loop operations
SD_EVENT_PRIORITY_IDLE(3) --- Set or retrieve the priority of event sources
SD_EVENT_PRIORITY_IMPORTANT(3) --- Set or retrieve the priority of event sources
SD_EVENT_PRIORITY_NORMAL(3) --- Set or retrieve the priority of event sources
sd_event_ref(3) --- Acquire and release an event loop object
sd_event_run(3) --- Run an event loop
SD_EVENT_RUNNING(3) --- Low-level event loop operations
sd_event_set_watchdog(3) --- Enable event loop watchdog support
sd_event_signal_handler_t(3) --- Add a UNIX process signal event source to an event loop
sd_event_source(3) --- Add an I/O event source to an event loop
sd_event_source_get_child_pid(3) --- Add a child process state change event source to an event loop
sd_event_source_get_description(3) --- Set or retrieve descriptive names of event sources
sd_event_source_get_enabled(3) --- Enable or disable event sources
sd_event_source_get_event(3) --- Retrieve the event loop of an event source
sd_event_source_get_io_events(3) --- Add an I/O event source to an event loop
sd_event_source_get_io_fd(3) --- Add an I/O event source to an event loop
sd_event_source_get_io_revents(3) --- Add an I/O event source to an event loop
sd_event_source_get_pending(3) --- Determine pending state of event sources
sd_event_source_get_priority(3) --- Set or retrieve the priority of event sources
sd_event_source_get_signal(3) --- Add a UNIX process signal event source to an event loop
sd_event_source_get_time(3) --- Add a timer event source to an event loop
sd_event_source_get_time_accuracy(3) --- Add a timer event source to an event loop
sd_event_source_get_time_clock(3) --- Add a timer event source to an event loop
sd_event_source_get_userdata(3) --- Set or retrieve user data pointer of event sources
sd_event_source_ref(3) --- Increase or decrease event source reference counters
sd_event_source_set_description(3) --- Set or retrieve descriptive names of event sources
sd_event_source_set_enabled(3) --- Enable or disable event sources
sd_event_source_set_io_events(3) --- Add an I/O event source to an event loop
sd_event_source_set_io_fd(3) --- Add an I/O event source to an event loop
sd_event_source_set_prepare(3) --- Set a preparation callback for event sources
sd_event_source_set_priority(3) --- Set or retrieve the priority of event sources
sd_event_source_set_time(3) --- Add a timer event source to an event loop
sd_event_source_set_time_accuracy(3) --- Add a timer event source to an event loop
sd_event_source_set_userdata(3) --- Set or retrieve user data pointer of event sources
sd_event_source_unref(3) --- Increase or decrease event source reference counters
sd_event_source_unrefp(3) --- Increase or decrease event source reference counters
sd_event_time_handler_t(3) --- Add a timer event source to an event loop
sd_event_unref(3) --- Acquire and release an event loop object
sd_event_unrefp(3) --- Acquire and release an event loop object
sd_event_wait(3) --- Low-level event loop operations
sd_get_machine_names(3) --- Determine available seats, sessions, logged in users and virtual machines/containers
sd_get_seats(3) --- Determine available seats, sessions, logged in users and virtual machines/containers
sd_get_sessions(3) --- Determine available seats, sessions, logged in users and virtual machines/containers
sd_get_uids(3) --- Determine available seats, sessions, logged in users and virtual machines/containers
SD_ID128_CONST_STR(3) --- APIs for processing 128-bit IDs
sd_id128_equal(3) --- APIs for processing 128-bit IDs
SD_ID128_FORMAT_STR(3) --- APIs for processing 128-bit IDs
SD_ID128_FORMAT_VAL(3) --- APIs for processing 128-bit IDs
sd_id128_from_string(3) --- Format or parse 128-bit IDs as strings
sd_id128_get_boot(3) --- Retrieve 128-bit IDs
sd_id128_get_invocation(3) --- Retrieve 128-bit IDs
sd_id128_get_machine(3) --- Retrieve 128-bit IDs
sd_id128_get_machine_app_specific(3) --- Retrieve 128-bit IDs
sd_id128_is_null(3) --- APIs for processing 128-bit IDs
SD_ID128_MAKE(3) --- APIs for processing 128-bit IDs
SD_ID128_MAKE_STR(3) --- APIs for processing 128-bit IDs
SD_ID128_NULL(3) --- APIs for processing 128-bit IDs
sd_id128_randomize(3) --- Generate 128-bit IDs
sd_id128_t(3) --- APIs for processing 128-bit IDs
sd_id128_to_string(3) --- Format or parse 128-bit IDs as strings
SD_INFO(3) --- APIs for new-style daemons
sd_is_fifo(3) --- Check the type of a file descriptor
sd_is_mq(3) --- Check the type of a file descriptor
sd_is_socket(3) --- Check the type of a file descriptor
sd_is_socket_inet(3) --- Check the type of a file descriptor
sd_is_socket_sockaddr(3) --- Check the type of a file descriptor
sd_is_socket_unix(3) --- Check the type of a file descriptor
sd_is_special(3) --- Check the type of a file descriptor
sd_journal(3) --- Open the system journal for reading
sd_journal_add_conjunction(3) --- Add or remove entry matches
sd_journal_add_disjunction(3) --- Add or remove entry matches
sd_journal_add_match(3) --- Add or remove entry matches
SD_JOURNAL_APPEND(3) --- Journal change notification interface
sd_journal_close(3) --- Open the system journal for reading
SD_JOURNAL_CURRENT_USER(3) --- Open the system journal for reading
sd_journal_enumerate_data(3) --- Read data fields from the current journal entry
sd_journal_enumerate_fields(3) --- Read used field names from the journal
sd_journal_enumerate_unique(3) --- Read unique data fields from the journal
sd_journal_flush_matches(3) --- Add or remove entry matches
SD_JOURNAL_FOREACH(3) --- Advance or set back the read pointer in the journal
SD_JOURNAL_FOREACH_BACKWARDS(3) --- Advance or set back the read pointer in the journal
SD_JOURNAL_FOREACH_DATA(3) --- Read data fields from the current journal entry
SD_JOURNAL_FOREACH_FIELD(3) --- Read used field names from the journal
SD_JOURNAL_FOREACH_UNIQUE(3) --- Read unique data fields from the journal
sd_journal_get_catalog(3) --- Retrieve message catalog entry
sd_journal_get_catalog_for_message_id(3) --- Retrieve message catalog entry
sd_journal_get_cursor(3) --- Get cursor string for or test cursor string against the current journal entry
sd_journal_get_cutoff_monotonic_usec(3) --- Read cut-off timestamps from the current journal entry
sd_journal_get_cutoff_realtime_usec(3) --- Read cut-off timestamps from the current journal entry
sd_journal_get_data(3) --- Read data fields from the current journal entry
sd_journal_get_data_threshold(3) --- Read data fields from the current journal entry
sd_journal_get_events(3) --- Journal change notification interface
sd_journal_get_fd(3) --- Journal change notification interface
sd_journal_get_monotonic_usec(3) --- Read timestamps from the current journal entry
sd_journal_get_realtime_usec(3) --- Read timestamps from the current journal entry
sd_journal_get_timeout(3) --- Journal change notification interface
sd_journal_get_usage(3) --- Journal disk usage
sd_journal_has_persistent_files(3) --- Query availability of runtime or persistent journal files.
sd_journal_has_runtime_files(3) --- Query availability of runtime or persistent journal files.
SD_JOURNAL_INVALIDATE(3) --- Journal change notification interface
SD_JOURNAL_LOCAL_ONLY(3) --- Open the system journal for reading
sd_journal_next(3) --- Advance or set back the read pointer in the journal
sd_journal_next_skip(3) --- Advance or set back the read pointer in the journal
SD_JOURNAL_NOP(3) --- Journal change notification interface
sd_journal_open(3) --- Open the system journal for reading
sd_journal_open_directory(3) --- Open the system journal for reading
sd_journal_open_directory_fd(3) --- Open the system journal for reading
sd_journal_open_files(3) --- Open the system journal for reading
sd_journal_open_files_fd(3) --- Open the system journal for reading
SD_JOURNAL_OS_ROOT(3) --- Open the system journal for reading
sd_journal_perror(3) --- Submit log entries to the journal
sd_journal_previous(3) --- Advance or set back the read pointer in the journal
sd_journal_previous_skip(3) --- Advance or set back the read pointer in the journal
sd_journal_print(3) --- Submit log entries to the journal
sd_journal_printv(3) --- Submit log entries to the journal
sd_journal_process(3) --- Journal change notification interface
sd_journal_query_unique(3) --- Read unique data fields from the journal
sd_journal_reliable_fd(3) --- Journal change notification interface
sd_journal_restart_data(3) --- Read data fields from the current journal entry
sd_journal_restart_fields(3) --- Read used field names from the journal
sd_journal_restart_unique(3) --- Read unique data fields from the journal
SD_JOURNAL_RUNTIME_ONLY(3) --- Open the system journal for reading
sd_journal_seek_cursor(3) --- Seek to a position in the journal
sd_journal_seek_head(3) --- Seek to a position in the journal
sd_journal_seek_monotonic_usec(3) --- Seek to a position in the journal
sd_journal_seek_realtime_usec(3) --- Seek to a position in the journal
sd_journal_seek_tail(3) --- Seek to a position in the journal
sd_journal_send(3) --- Submit log entries to the journal
sd_journal_sendv(3) --- Submit log entries to the journal
sd_journal_set_data_threshold(3) --- Read data fields from the current journal entry
sd_journal_stream_fd(3) --- Create log stream file descriptor to the journal
SD_JOURNAL_SUPPRESS_LOCATION(3) --- Submit log entries to the journal
SD_JOURNAL_SYSTEM(3) --- Open the system journal for reading
sd_journal_test_cursor(3) --- Get cursor string for or test cursor string against the current journal entry
sd_journal_wait(3) --- Journal change notification interface
sd_listen_fds(3) --- Check for file descriptors passed by the system manager
SD_LISTEN_FDS_START(3) --- Check for file descriptors passed by the system manager
sd_listen_fds_with_names(3) --- Check for file descriptors passed by the system manager
sd_login_monitor(3) --- Monitor login sessions, seats, users and virtual machines/containers
sd_login_monitor_flush(3) --- Monitor login sessions, seats, users and virtual machines/containers
sd_login_monitor_get_events(3) --- Monitor login sessions, seats, users and virtual machines/containers
sd_login_monitor_get_fd(3) --- Monitor login sessions, seats, users and virtual machines/containers
sd_login_monitor_get_timeout(3) --- Monitor login sessions, seats, users and virtual machines/containers
sd_login_monitor_new(3) --- Monitor login sessions, seats, users and virtual machines/containers
sd_login_monitor_unref(3) --- Monitor login sessions, seats, users and virtual machines/containers
sd_login_monitor_unrefp(3) --- Monitor login sessions, seats, users and virtual machines/containers
sd_machine_get_class(3) --- Determine the class and network interface indices of a locally running virtual machine or container.
sd_machine_get_ifindices(3) --- Determine the class and network interface indices of a locally running virtual machine or container.
SD_NOTICE(3) --- APIs for new-style daemons
sd_notify(3) --- Notify service manager about start-up completion and other service status changes
sd_notifyf(3) --- Notify service manager about start-up completion and other service status changes
sd_peer_get_cgroup(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_peer_get_machine_name(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_peer_get_owner_uid(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_peer_get_session(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_peer_get_slice(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_peer_get_unit(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_peer_get_user_slice(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_peer_get_user_unit(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_get_cgroup(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_get_machine_name(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_get_owner_uid(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_get_session(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_get_slice(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_get_unit(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_get_user_slice(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_get_user_unit(3) --- Determine the owner uid of the user unit or session, or the session, user unit, system unit, container/VM or slice that a specific PID or socket peer belongs to.
sd_pid_notify(3) --- Notify service manager about start-up completion and other service status changes
sd_pid_notify_with_fds(3) --- Notify service manager about start-up completion and other service status changes
sd_pid_notifyf(3) --- Notify service manager about start-up completion and other service status changes
sd_seat_can_graphical(3) --- Determine state of a specific seat
sd_seat_can_multi_session(3) --- Determine state of a specific seat
sd_seat_can_tty(3) --- Determine state of a specific seat
sd_seat_get_active(3) --- Determine state of a specific seat
sd_seat_get_sessions(3) --- Determine state of a specific seat
sd_session_get_class(3) --- Determine state of a specific session
sd_session_get_desktop(3) --- Determine state of a specific session
sd_session_get_display(3) --- Determine state of a specific session
sd_session_get_remote_host(3) --- Determine state of a specific session
sd_session_get_remote_user(3) --- Determine state of a specific session
sd_session_get_seat(3) --- Determine state of a specific session
sd_session_get_service(3) --- Determine state of a specific session
sd_session_get_state(3) --- Determine state of a specific session
sd_session_get_tty(3) --- Determine state of a specific session
sd_session_get_type(3) --- Determine state of a specific session
sd_session_get_uid(3) --- Determine state of a specific session
sd_session_get_vt(3) --- Determine state of a specific session
sd_session_is_active(3) --- Determine state of a specific session
sd_session_is_remote(3) --- Determine state of a specific session
sd_uid_get_display(3) --- Determine login state of a specific Unix user ID
sd_uid_get_seats(3) --- Determine login state of a specific Unix user ID
sd_uid_get_sessions(3) --- Determine login state of a specific Unix user ID
sd_uid_get_state(3) --- Determine login state of a specific Unix user ID
sd_uid_is_on_seat(3) --- Determine login state of a specific Unix user ID
SD_WARNING(3) --- APIs for new-style daemons
sd_watchdog_enabled(3) --- Check whether the service manager expects watchdog keep-alive notifications from a service
shutdown(8) --- Halt, power-off or reboot the machine
sleep.conf.d(5) --- Suspend and hibernation configuration file
sysctl.d(5) --- Configure kernel parameters at boot
system.conf.d(5) --- System and session service manager configuration files
systemctl(1) --- Control the systemd system and service manager
systemd(1) --- systemd system and service manager
systemd-analyze(1) --- Analyze and debug system manager
systemd-ask-password(1) --- Query the user for a system password
systemd-ask-password-console.path(8) --- Query the user for system passwords on the console and via wall
systemd-ask-password-console.service(8) --- Query the user for system passwords on the console and via wall
systemd-ask-password-wall.path(8) --- Query the user for system passwords on the console and via wall
systemd-ask-password-wall.service(8) --- Query the user for system passwords on the console and via wall
systemd-backlight(8) --- Load and save the display backlight brightness at boot and shutdown
systemd-backlight@.service(8) --- Load and save the display backlight brightness at boot and shutdown
systemd-binfmt(8) --- Configure additional binary formats for executables at boot
systemd-binfmt.service(8) --- Configure additional binary formats for executables at boot
systemd-cat(1) --- Connect a pipeline or program's output with the journal
systemd-cgls(1) --- Recursively show control group contents
systemd-cgtop(1) --- Show top control groups by their resource usage
systemd-coredump(8) --- Acquire, save and process core dumps
systemd-coredump.socket(8) --- Acquire, save and process core dumps
systemd-coredump@.service(8) --- Acquire, save and process core dumps
systemd-cryptsetup(8) --- Full disk decryption logic
systemd-cryptsetup-generator(8) --- Unit generator for
systemd-cryptsetup@.service(8) --- Full disk decryption logic
systemd-debug-generator(8) --- Generator for enabling a runtime debug shell and masking specific units at boot
systemd-delta(1) --- Find overridden configuration files
systemd-detect-virt(1) --- Detect execution in a virtualized environment
systemd-environment-d-generator(8) --- Load variables specified by
systemd-escape(1) --- Escape strings for usage in systemd unit names
systemd-fsck(8) --- File system checker logic
systemd-fsck-root.service(8) --- File system checker logic
systemd-fsck@.service(8) --- File system checker logic
systemd-fsckd(8) --- File system check progress reporting
systemd-fsckd.service(8) --- File system check progress reporting
systemd-fsckd.socket(8) --- File system check progress reporting
systemd-fstab-generator(8) --- Unit generator for /etc/fstab
systemd-getty-generator(8) --- Generator for enabling getty instances on the console
systemd-gpt-auto-generator(8) --- Generator for automatically discovering and mounting root,
systemd-growfs(8) --- Creating and growing file systems on demand
systemd-growfs@.service(8) --- Creating and growing file systems on demand
systemd-halt.service(8) --- System shutdown logic
systemd-hibernate-resume(8) --- Resume from hibernation
systemd-hibernate-resume-generator(8) --- Unit generator for resume= kernel parameter
systemd-hibernate-resume@.service(8) --- Resume from hibernation
systemd-hibernate.service(8) --- System sleep state logic
systemd-hostnamed(8) --- Host name bus mechanism
systemd-hostnamed.service(8) --- Host name bus mechanism
systemd-hwdb(8) --- hardware database management tool
systemd-hybrid-sleep.service(8) --- System sleep state logic
systemd-importd(8) --- VM and container image import and export service
systemd-importd.service(8) --- VM and container image import and export service
systemd-inhibit(1) --- Execute a program with an inhibition lock taken
systemd-initctl(8) --- /dev/initctl compatibility
systemd-initctl.service(8) --- /dev/initctl compatibility
systemd-initctl.socket(8) --- /dev/initctl compatibility
systemd-journal-gatewayd(8) --- HTTP server for journal events
systemd-journal-gatewayd.service(8) --- HTTP server for journal events
systemd-journal-gatewayd.socket(8) --- HTTP server for journal events
systemd-journal-remote(8) --- Receive journal messages over the network
systemd-journal-upload(8) --- Send journal messages over the network
systemd-journald(8) --- Journal service
systemd-journald-audit.socket(8) --- Journal service
systemd-journald-dev-log.socket(8) --- Journal service
systemd-journald.service(8) --- Journal service
systemd-journald.socket(8) --- Journal service
systemd-kexec.service(8) --- System shutdown logic
systemd-localed(8) --- Locale bus mechanism
systemd-localed.service(8) --- Locale bus mechanism
systemd-logind(8) --- Login manager
systemd-logind.service(8) --- Login manager
systemd-machine-id-commit.service(8) --- Commit a transient machine ID to disk
systemd-machine-id-setup(1) --- Initialize the machine ID in /etc/machine-id
systemd-machined(8) --- Virtual machine and container registration manager
systemd-machined.service(8) --- Virtual machine and container registration manager
systemd-makefs(8) --- Creating and growing file systems on demand
systemd-makefs@.service(8) --- Creating and growing file systems on demand
systemd-makeswap@.service(8) --- Creating and growing file systems on demand
systemd-modules-load(8) --- Load kernel modules at boot
systemd-modules-load.service(8) --- Load kernel modules at boot
systemd-mount(1) --- Establish and destroy transient mount or auto-mount points
systemd-networkd(8) --- Network manager
systemd-networkd-wait-online(8) --- Wait for network to come online
systemd-networkd-wait-online.service(8) --- Wait for network to come online
systemd-networkd.service(8) --- Network manager
systemd-notify(1) --- Notify service manager about start-up completion and other daemon status changes
systemd-nspawn(1) --- Spawn a namespace container for debugging, testing and building
systemd-path(1) --- List and query system and user paths
systemd-poweroff.service(8) --- System shutdown logic
systemd-quotacheck(8) --- File system quota checker logic
systemd-quotacheck.service(8) --- File system quota checker logic
systemd-random-seed(8) --- Load and save the system random seed at boot and shutdown
systemd-random-seed.service(8) --- Load and save the system random seed at boot and shutdown
systemd-rc-local-generator(8) --- Compatibility generator for starting
systemd-reboot.service(8) --- System shutdown logic
systemd-remount-fs(8) --- Remount root and kernel file systems
systemd-remount-fs.service(8) --- Remount root and kernel file systems
systemd-resolve(1) --- Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services
systemd-resolved(8) --- Network Name Resolution manager
systemd-resolved.service(8) --- Network Name Resolution manager
systemd-rfkill(8) --- Load and save the RF kill switch state at boot and change
systemd-rfkill.service(8) --- Load and save the RF kill switch state at boot and change
systemd-rfkill.socket(8) --- Load and save the RF kill switch state at boot and change
systemd-run(1) --- Run programs in transient scope units, service units, or path-, socket-, or timer-triggered service units
systemd-shutdown(8) --- System shutdown logic
systemd-sleep(8) --- System sleep state logic
systemd-sleep.conf(5) --- Suspend and hibernation configuration file
systemd-socket-activate(1) --- Test socket activation of daemons
systemd-socket-proxyd(8) --- Bidirectionally proxy local sockets to another (possibly remote) socket.
systemd-suspend-then-hibernate.service(8) --- System sleep state logic
systemd-suspend.service(8) --- System sleep state logic
systemd-sysctl(8) --- Configure kernel parameters at boot
systemd-sysctl.service(8) --- Configure kernel parameters at boot
systemd-system-update-generator(8) --- Generator for redirecting boot to offline update mode
systemd-system.conf(5) --- System and session service manager configuration files
systemd-sysusers(8) --- Allocate system users and groups
systemd-sysusers.service(8) --- Allocate system users and groups
systemd-sysv-generator(8) --- Unit generator for SysV init scripts
systemd-timedated(8) --- Time and date bus mechanism
systemd-timedated.service(8) --- Time and date bus mechanism
systemd-timesyncd(8) --- Network Time Synchronization
systemd-timesyncd.service(8) --- Network Time Synchronization
systemd-tmpfiles(8) --- Creates, deletes and cleans up volatile and temporary files and directories
systemd-tmpfiles-clean.service(8) --- Creates, deletes and cleans up volatile and temporary files and directories
systemd-tmpfiles-clean.timer(8) --- Creates, deletes and cleans up volatile and temporary files and directories
systemd-tmpfiles-setup-dev.service(8) --- Creates, deletes and cleans up volatile and temporary files and directories
systemd-tmpfiles-setup.service(8) --- Creates, deletes and cleans up volatile and temporary files and directories
systemd-tty-ask-password-agent(1) --- List or process pending systemd password requests
systemd-udevd(8) --- Device event managing daemon
systemd-udevd-control.socket(8) --- Device event managing daemon
systemd-udevd-kernel.socket(8) --- Device event managing daemon
systemd-udevd.service(8) --- Device event managing daemon
systemd-umount(1) --- Establish and destroy transient mount or auto-mount points
systemd-update-done(8) --- Mark
systemd-update-done.service(8) --- Mark
systemd-update-utmp(8) --- Write audit and utmp updates at bootup, runlevel changes and shutdown
systemd-update-utmp-runlevel.service(8) --- Write audit and utmp updates at bootup, runlevel changes and shutdown
systemd-update-utmp.service(8) --- Write audit and utmp updates at bootup, runlevel changes and shutdown
systemd-user-sessions(8) --- Permit user logins after boot, prohibit user logins at shutdown
systemd-user-sessions.service(8) --- Permit user logins after boot, prohibit user logins at shutdown
systemd-user.conf(5) --- System and session service manager configuration files
systemd-veritysetup(8) --- Disk integrity protection logic
systemd-veritysetup-generator(8) --- Unit generator for integrity protected block devices
systemd-veritysetup@.service(8) --- Disk integrity protection logic
systemd-volatile-root(8) --- Make the root file system volatile
systemd-volatile-root.service(8) --- Make the root file system volatile
systemd.automount(5) --- Automount unit configuration
systemd.device(5) --- Device unit configuration
systemd.directives(7) --- Index of configuration directives
systemd.dnssd(5) --- DNS-SD configuration
systemd.environment-generator(7) --- systemd environment file generators
systemd.exec(5) --- Execution environment configuration
systemd.generator(7) --- systemd unit generators
systemd.journal-fields(7) --- Special journal fields
systemd.kill(5) --- Process killing procedure configuration
systemd.link(5) --- Network device configuration
systemd.mount(5) --- Mount unit configuration
systemd.negative(5) --- DNSSEC trust anchor configuration files
systemd.netdev(5) --- Virtual Network Device configuration
systemd.network(5) --- Network configuration
systemd.nspawn(5) --- Container settings
systemd.offline-updates(7) --- Implementation of offline updates in systemd
systemd.path(5) --- Path unit configuration
systemd.positive(5) --- DNSSEC trust anchor configuration files
systemd.preset(5) --- Service enablement presets
systemd.resource-control(5) --- Resource control unit settings
systemd.scope(5) --- Scope unit configuration
systemd.service(5) --- Service unit configuration
systemd.slice(5) --- Slice unit configuration
systemd.socket(5) --- Socket unit configuration
systemd.special(7) --- Special systemd units
systemd.swap(5) --- Swap unit configuration
systemd.target(5) --- Target unit configuration
systemd.time(7) --- Time and date specifications
systemd.timer(5) --- Timer unit configuration
systemd.unit(5) --- Unit configuration
sysusers.d(5) --- Declarative allocation of system users and groups

 

T

telinit(8) --- Change SysV runlevel
timedatectl(1) --- Control the system time and date
timesyncd.conf(5) --- Network Time Synchronization configuration files
timesyncd.conf.d(5) --- Network Time Synchronization configuration files
tmpfiles.d(5) --- Configuration for creation, deletion and cleaning of volatile and temporary files

 

U

udev(7) --- Dynamic device management
udev.conf(5) --- Configuration for device event managing daemon
udev_device_get_action(3) --- Query device properties
udev_device_get_devlinks_list_entry(3) --- Retrieve or set device attributes
udev_device_get_devnode(3) --- Query device properties
udev_device_get_devnum(3) --- Query device properties
udev_device_get_devpath(3) --- Query device properties
udev_device_get_devtype(3) --- Query device properties
udev_device_get_driver(3) --- Query device properties
udev_device_get_is_initialized(3) --- Query device properties
udev_device_get_parent(3) --- Query device properties
udev_device_get_parent_with_subsystem_devtype(3) --- Query device properties
udev_device_get_properties_list_entry(3) --- Retrieve or set device attributes
udev_device_get_property_value(3) --- Retrieve or set device attributes
udev_device_get_subsystem(3) --- Query device properties
udev_device_get_sysattr_list_entry(3) --- Retrieve or set device attributes
udev_device_get_sysattr_value(3) --- Retrieve or set device attributes
udev_device_get_sysname(3) --- Query device properties
udev_device_get_sysnum(3) --- Query device properties
udev_device_get_syspath(3) --- Query device properties
udev_device_get_tags_list_entry(3) --- Retrieve or set device attributes
udev_device_get_udev(3) --- Query device properties
udev_device_has_tag(3) --- Retrieve or set device attributes
udev_device_new_from_device_id(3) --- Create, acquire and release a udev device object
udev_device_new_from_devnum(3) --- Create, acquire and release a udev device object
udev_device_new_from_environment(3) --- Create, acquire and release a udev device object
udev_device_new_from_subsystem_sysname(3) --- Create, acquire and release a udev device object
udev_device_new_from_syspath(3) --- Create, acquire and release a udev device object
udev_device_ref(3) --- Create, acquire and release a udev device object
udev_device_set_sysattr_value(3) --- Retrieve or set device attributes
udev_device_unref(3) --- Create, acquire and release a udev device object
udev_enumerate_add_match_is_initialized(3) --- Modify filters
udev_enumerate_add_match_parent(3) --- Modify filters
udev_enumerate_add_match_property(3) --- Modify filters
udev_enumerate_add_match_subsystem(3) --- Modify filters
udev_enumerate_add_match_sysattr(3) --- Modify filters
udev_enumerate_add_match_sysname(3) --- Modify filters
udev_enumerate_add_match_tag(3) --- Modify filters
udev_enumerate_add_nomatch_subsystem(3) --- Modify filters
udev_enumerate_add_nomatch_sysattr(3) --- Modify filters
udev_enumerate_add_syspath(3) --- Query or modify a udev enumerate object
udev_enumerate_get_list_entry(3) --- Query or modify a udev enumerate object
udev_enumerate_get_udev(3) --- Query or modify a udev enumerate object
udev_enumerate_new(3) --- Create, acquire and release a udev enumerate object
udev_enumerate_ref(3) --- Create, acquire and release a udev enumerate object
udev_enumerate_scan_devices(3) --- Query or modify a udev enumerate object
udev_enumerate_scan_subsystems(3) --- Query or modify a udev enumerate object
udev_enumerate_unref(3) --- Create, acquire and release a udev enumerate object
udev_list_entry(3) --- Iterate and access udev lists
udev_list_entry_get_by_name(3) --- Iterate and access udev lists
udev_list_entry_get_name(3) --- Iterate and access udev lists
udev_list_entry_get_next(3) --- Iterate and access udev lists
udev_list_entry_get_value(3) --- Iterate and access udev lists
udev_monitor_enable_receiving(3) --- Query and modify device monitor
udev_monitor_filter_add_match_subsystem_devtype(3) --- Modify filters
udev_monitor_filter_add_match_tag(3) --- Modify filters
udev_monitor_filter_remove(3) --- Modify filters
udev_monitor_filter_update(3) --- Modify filters
udev_monitor_get_fd(3) --- Query and modify device monitor
udev_monitor_get_udev(3) --- Query and modify device monitor
udev_monitor_new_from_netlink(3) --- Create, acquire and release a udev monitor object
udev_monitor_receive_device(3) --- Query and modify device monitor
udev_monitor_ref(3) --- Create, acquire and release a udev monitor object
udev_monitor_set_receive_buffer_size(3) --- Query and modify device monitor
udev_monitor_unref(3) --- Create, acquire and release a udev monitor object
udev_new(3) --- Create, acquire and release a udev context object
udev_ref(3) --- Create, acquire and release a udev context object
udev_unref(3) --- Create, acquire and release a udev context object
udevadm(8) --- udev management tool
user.conf.d(5) --- System and session service manager configuration files

 

SEE ALSO

systemd.directives(7)

This index contains 712 entries, referring to 251 individual manual pages.


 

Index

NAME
3
B
C
D
E
F
H
I
J
K
L
M
N
O
P
R
S
T
U
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:57 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.SPECIAL

SYSTEMD.SPECIAL

Section: systemd.special (7)
Updated:
Index Return to Main Contents
 

NAME

systemd.special - Special systemd units  

SYNOPSIS

basic.target, bluetooth.target, cryptsetup-pre.target, cryptsetup.target, ctrl-alt-del.target, default.target, emergency.target, exit.target, final.target, getty.target, getty-pre.target, graphical.target, halt.target, hibernate.target, hybrid-sleep.target, suspend-then-hibernate.target, initrd-fs.target, initrd-root-device.target, initrd-root-fs.target, kbrequest.target, kexec.target, local-fs-pre.target, local-fs.target, machines.target multi-user.target, network-online.target, network-pre.target, network.target, nss-lookup.target, nss-user-lookup.target, paths.target, poweroff.target, printer.target, reboot.target, remote-cryptsetup.target, remote-fs-pre.target, remote-fs.target, rescue.target, rpcbind.target, runlevel2.target, runlevel3.target, runlevel4.target, runlevel5.target, shutdown.target, sigpwr.target, sleep.target, slices.target, smartcard.target, sockets.target, sound.target, suspend.target, swap.target, sysinit.target, system-update.target, time-sync.target, timers.target, umount.target, -.slice, system.slice, user.slice, machine.slice, -.mount, dbus.service, dbus.socket, display-manager.service, init.scope, syslog.socket, system-update-cleanup.service  

DESCRIPTION

A few units are treated specially by systemd. Many of them have special internal semantics and cannot be renamed, while others simply have a standard meaning and should be present on all systems.  

SPECIAL SYSTEM UNITS

-.mount

The root mount point, i.e. the mount unit for the / path. This unit is unconditionally active, during the entire time the system is up, as this mount point is where the basic userspace is running from.

basic.target

A special target unit covering basic boot-up.

systemd automatically adds dependency of the type After= for this target unit to all services (except for those with DefaultDependencies=no).

Usually, this should pull-in all local mount points plus /var, /tmp and /var/tmp, swap devices, sockets, timers, path units and other basic initialization necessary for general purpose daemons. The mentioned mount points are special cased to allow them to be remote.

This target usually does not pull in any non-target units directly, but rather does so indirectly via other early boot targets. It is instead meant as a synchronization point for late boot services. Refer to bootup(7) for details on the targets involved.

ctrl-alt-del.target

systemd starts this target whenever Control+Alt+Del is pressed on the console. Usually, this should be aliased (symlinked) to reboot.target.

cryptsetup.target

A target that pulls in setup services for all encrypted block devices.

dbus.service

A special unit for the D-Bus bus daemon. As soon as this service is fully started up systemd will connect to it and register its service.

dbus.socket

A special unit for the D-Bus system bus socket. All units with Type=dbus automatically gain a dependency on this unit.

default.target

The default unit systemd starts at bootup. Usually, this should be aliased (symlinked) to multi-user.target or graphical.target.

The default unit systemd starts at bootup can be overridden with the systemd.unit= kernel command line option.

display-manager.service

The display manager service. Usually, this should be aliased (symlinked) to gdm.service or a similar display manager service.

emergency.target

A special target unit that starts an emergency shell on the main console. This target does not pull in any services or mounts. It is the most minimal version of starting the system in order to acquire an interactive shell; the only processes running are usually just the system manager (PID 1) and the shell process. This unit is supposed to be used with the kernel command line option systemd.unit=; it is also used when a file system check on a required file system fails, and boot-up cannot continue. Compare with rescue.target, which serves a similar purpose, but also starts the most basic services and mounts all file systems.

Use the "systemd.unit=emergency.target" kernel command line option to boot into this mode. A short alias for this kernel command line option is "emergency", for compatibility with SysV.

In many ways booting into emergency.target is similar to the effect of booting with "init=/bin/sh" on the kernel command line, except that emergency mode provides you with the full system and service manager, and allows starting individual units in order to continue the boot process in steps.

exit.target

A special service unit for shutting down the system or user service manager. It is equivalent to poweroff.target on non-container systems, and also works in containers.

systemd will start this unit when it receives the SIGTERM or SIGINT signal when running as user service daemon.

Normally, this (indirectly) pulls in shutdown.target, which in turn should be conflicted by all units that want to be scheduled for shutdown when the service manager starts to exit.

final.target

A special target unit that is used during the shutdown logic and may be used to pull in late services after all normal services are already terminated and all mounts unmounted.

getty.target

A special target unit that pulls in statically configured local TTY getty instances.

graphical.target

A special target unit for setting up a graphical login screen. This pulls in multi-user.target.

Units that are needed for graphical logins shall add Wants= dependencies for their unit to this unit (or multi-user.target) during installation. This is best configured via WantedBy=graphical.target in the unit's "[Install]" section.

hibernate.target

A special target unit for hibernating the system. This pulls in sleep.target.

hybrid-sleep.target

A special target unit for hibernating and suspending the system at the same time. This pulls in sleep.target.

suspend-then-hibernate.target

A special target unit for suspending the system for a period of time, waking it and putting it into hibernate. This pulls in sleep.target.

halt.target

A special target unit for shutting down and halting the system. Note that this target is distinct from poweroff.target in that it generally really just halts the system rather than powering it down.

Applications wanting to halt the system should not start this unit directly, but should instead execute systemctl halt (possibly with the --no-block option) or call systemd(1)'s org.freedesktop.systemd1.Manager.Halt D-Bus method directly.

init.scope

This scope unit is where the system and service manager (PID 1) itself resides. It is active as long as the system is running.

initrd-fs.target

systemd-fstab-generator(3) automatically adds dependencies of type Before= to sysroot-usr.mount and all mount points found in /etc/fstab that have x-initrd.mount and not have noauto mount options set.

initrd-root-device.target

A special initrd target unit that is reached when the root filesystem device is available, but before it has been mounted. systemd-fstab-generator(3) and systemd-gpt-auto-generator(3) automatically setup the appropriate dependencies to make this happen.

initrd-root-fs.target

systemd-fstab-generator(3) automatically adds dependencies of type Before= to the sysroot.mount unit, which is generated from the kernel command line.

kbrequest.target

systemd starts this target whenever Alt+ArrowUp is pressed on the console. Note that any user with physical access to the machine will be able to do this, without authentication, so this should be used carefully.

kexec.target

A special target unit for shutting down and rebooting the system via kexec.

Applications wanting to reboot the system should not start this unit directly, but should instead execute systemctl kexec (possibly with the --no-block option) or call systemd(1)'s org.freedesktop.systemd1.Manager.KExec D-Bus method directly.

local-fs.target

systemd-fstab-generator(3) automatically adds dependencies of type Before= to all mount units that refer to local mount points for this target unit. In addition, it adds dependencies of type Wants= to this target unit for those mounts listed in /etc/fstab that have the auto mount option set.

machines.target

A standard target unit for starting all the containers and other virtual machines. See systemd-nspawn@.service for an example.

multi-user.target

A special target unit for setting up a multi-user system (non-graphical). This is pulled in by graphical.target.

Units that are needed for a multi-user system shall add Wants= dependencies for their unit to this unit during installation. This is best configured via WantedBy=multi-user.target in the unit's "[Install]" section.

network-online.target

Units that strictly require a configured network connection should pull in network-online.target (via a Wants= type dependency) and order themselves after it. This target unit is intended to pull in a service that delays further execution until the network is sufficiently set up. What precisely this requires is left to the implementation of the network managing service.

Note the distinction between this unit and network.target. This unit is an active unit (i.e. pulled in by the consumer rather than the provider of this functionality) and pulls in a service which possibly adds substantial delays to further execution. In contrast, network.target is a passive unit (i.e. pulled in by the provider of the functionality, rather than the consumer) that usually does not delay execution much. Usually, network.target is part of the boot of most systems, while network-online.target is not, except when at least one unit requires it. Also see m[blue]Running Services After the Network is upm[][1] for more information.

All mount units for remote network file systems automatically pull in this unit, and order themselves after it. Note that networking daemons that simply provide functionality to other hosts generally do not need to pull this in.

Note that this unit is only useful during the original system start-up logic. After the system has completed booting up, it will not track the online state of the system anymore. Due to this it cannot be used as a network connection monitor concept, it is purely a one-time system start-up concept.

paths.target

A special target unit that sets up all path units (see systemd.path(5) for details) that shall be active after boot.

It is recommended that path units installed by applications get pulled in via Wants= dependencies from this unit. This is best configured via a WantedBy=paths.target in the path unit's "[Install]" section.

poweroff.target

A special target unit for shutting down and powering off the system.

Applications wanting to reboot the system should not start this unit directly, but should instead execute systemctl poweroff (possibly with the --no-block option) or call systemd-logind(8)'s org.freedesktop.login1.Manager.PowerOff D-Bus method directly.

runlevel0.target is an alias for this target unit, for compatibility with SysV.

reboot.target

A special target unit for shutting down and rebooting the system.

Applications wanting to reboot the system should not start this unit directly, but should instead execute systemctl reboot (possibly with the --no-block option) or call systemd-logind(8)'s org.freedesktop.login1.Manager.Reboot D-Bus method directly.

runlevel6.target is an alias for this target unit, for compatibility with SysV.

remote-cryptsetup.target

Similar to cryptsetup.target, but for encrypted devices which are accessed over the network. It is used for crypttab(8) entries marked with _netdev.

remote-fs.target

Similar to local-fs.target, but for remote mount points.

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 "$remote_fs" facility.

rescue.target

A special target unit that pulls in the base system (including system mounts) and spawns a rescue shell. Isolate to this target in order to administer the system in single-user mode with all file systems mounted but with no services running, except for the most basic. Compare with emergency.target, which is much more reduced and does not provide the file systems or most basic services. Compare with multi-user.target, this target could be seen as single-user.target.

runlevel1.target is an alias for this target unit, for compatibility with SysV.

Use the "systemd.unit=rescue.target" kernel command line option to boot into this mode. A short alias for this kernel command line option is "1", for compatibility with SysV.

runlevel2.target, runlevel3.target, runlevel4.target, runlevel5.target

These are targets that are called whenever the SysV compatibility code asks for runlevel 2, 3, 4, 5, respectively. It is a good idea to make this an alias for (i.e. symlink to) graphical.target (for runlevel 5) or multi-user.target (the others).

shutdown.target

A special target unit that terminates the services on system shutdown.

Services that shall be terminated on system shutdown shall add Conflicts= and Before= dependencies to this unit for their service unit, which is implicitly done when DefaultDependencies=yes is set (the default).

sigpwr.target

A special target that is started when systemd receives the SIGPWR process signal, which is normally sent by the kernel or UPS daemons when power fails.

sleep.target

A special target unit that is pulled in by suspend.target, hibernate.target and hybrid-sleep.target and may be used to hook units into the sleep state logic.

slices.target

A special target unit that sets up all slice units (see systemd.slice(5) for details) that shall be active after boot. By default the generic system.slice slice unit, as well as the root slice unit -.slice, is pulled in and ordered before this unit (see below).

It's a good idea to add WantedBy=slices.target lines to the "[Install]" section of all slices units that may be installed dynamically.

sockets.target

A special target unit that sets up all socket units (see systemd.socket(5) for details) that shall be active after boot.

Services that can be socket-activated shall add Wants= dependencies to this unit for their socket unit during installation. This is best configured via a WantedBy=sockets.target in the socket unit's "[Install]" section.

suspend.target

A special target unit for suspending the system. This pulls in sleep.target.

swap.target

Similar to local-fs.target, but for swap partitions and swap files.

sysinit.target

systemd automatically adds dependencies of the types Requires= and After= for this target unit to all services (except for those with DefaultDependencies=no).

This target pulls in the services required for system initialization. System services pulled in by this target should declare DefaultDependencies=no and specify all their dependencies manually, including access to anything more than a read only root filesystem. For details on the dependencies of this target, refer to bootup(7).

syslog.socket

The socket unit syslog implementations should listen on. All userspace log messages will be made available on this socket. For more information about syslog integration, please consult the m[blue]Syslog Interfacem[][2] document.

system-update.target, system-update-cleanup.service

A special target unit that is used for offline system updates. systemd-system-update-generator(8) will redirect the boot process to this target if /system-update exists. For more information see systemd.offline-updates(7).

Updates should happen before the system-update.target is reached, and the services which implement them should cause the machine to reboot. As a safety measure, if this does not happen, and /system-update still exists after system-update.target is reached, system-update-cleanup.service will remove this symlink and reboot the machine.

timers.target

A special target unit that sets up all timer units (see systemd.timer(5) for details) that shall be active after boot.

It is recommended that timer units installed by applications get pulled in via Wants= dependencies from this unit. This is best configured via WantedBy=timers.target in the timer unit's "[Install]" section.

umount.target

A special target unit that unmounts all mount and automount points on system shutdown.

Mounts that shall be unmounted on system shutdown shall add Conflicts dependencies to this unit for their mount unit, which is implicitly done when DefaultDependencies=yes is set (the default).

 

SPECIAL SYSTEM UNITS FOR DEVICES

Some target units are automatically pulled in as devices of certain kinds show up in the system. These may be used to automatically activate various services based on the specific type of the available hardware.

bluetooth.target

This target is started automatically as soon as a Bluetooth controller is plugged in or becomes available at boot.

This may be used to pull in Bluetooth management daemons dynamically when Bluetooth hardware is found.

printer.target

This target is started automatically as soon as a printer is plugged in or becomes available at boot.

This may be used to pull in printer management daemons dynamically when printer hardware is found.

smartcard.target

This target is started automatically as soon as a smartcard controller is plugged in or becomes available at boot.

This may be used to pull in smartcard management daemons dynamically when smartcard hardware is found.

sound.target

This target is started automatically as soon as a sound card is plugged in or becomes available at boot.

This may be used to pull in audio management daemons dynamically when audio hardware is found.

 

SPECIAL PASSIVE SYSTEM UNITS

A number of special system targets are defined that can be used to properly order boot-up of optional services. These targets are generally not part of the initial boot transaction, unless they are explicitly pulled in by one of the implementing services. Note specifically that these passive target units are generally not pulled in by the consumer of a service, but by the provider of the service. This means: a consuming service should order itself after these targets (as appropriate), but not pull it in. A providing service should order itself before these targets (as appropriate) and pull it in (via a Wants= type dependency).

Note that these passive units cannot be started manually, i.e. "systemctl start time-sync.target" will fail with an error. They can only be pulled in by dependency. This is enforced since they exist for ordering purposes only and thus are not useful as only unit within a transaction.

cryptsetup-pre.target

This passive target unit may be pulled in by services that want to run before any encrypted block device is set up. All encrypted block devices are set up after this target has been reached. Since the shutdown order is implicitly the reverse start-up order between units, this target is particularly useful to ensure that a service is shut down only after all encrypted block devices are fully stopped.

getty-pre.target

A special passive target unit. Users of this target are expected to pull it in the boot transaction via a dependency (e.g. Wants=). Order your unit before this unit if you want to make use of the console just before getty is started.

local-fs-pre.target

This target unit is automatically ordered before all local mount points marked with auto (see above). It can be used to execute certain units before all local mounts.

network.target

This unit is supposed to indicate when network functionality is available, but it is only very weakly defined what that is supposed to mean, with one exception: at shutdown, a unit that is ordered after network.target will be stopped before the network --- to whatever level it might be set up then --- is shut down. It is hence useful when writing service files that require network access on shutdown, which should order themselves after this target, but not pull it in. Also see m[blue]Running Services After the Network is upm[][1] for more information. Also see network-online.target described above.

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 "$network" facility.

network-pre.target

This passive target unit may be pulled in by services that want to run before any network is set up, for example for the purpose of setting up a firewall. All network management software orders itself after this target, but does not pull it in.

nss-lookup.target

A target that should be used as synchronization point for all host/network name service lookups. Note that this is independent of user/group name lookups for which nss-user-lookup.target should be used. All services for which the availability of full host/network name resolution is essential should be ordered after this target, but not pull it in. 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 "$named" facility.

nss-user-lookup.target

A target that should be used as synchronization point for all user/group name service lookups. Note that this is independent of host/network name lookups for which nss-lookup.target should be used. All services for which the availability of the full user/group database is essential should be ordered after this target, but not pull it in. Note that system users are always resolvable, and hence do not require any special ordering against this target.

remote-fs-pre.target

This target unit is automatically ordered before all mount point units (see above) and cryptsetup devices marked with the _netdev. It can be used to run certain units before remote encrypted devices and mounts are established. Note that this unit is generally not part of the initial transaction, unless the unit that wants to be ordered before all remote mounts pulls it in via a Wants= type dependency. If the unit wants to be pulled in by the first remote mount showing up, it should use network-online.target (see above).

rpcbind.target

The portmapper/rpcbind pulls in this target and orders itself before it, to indicate its availability. 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 "$portmap" facility.

time-sync.target

Services responsible for synchronizing the system clock from a remote source (such as NTP client implementations) should pull in this target and order themselves before it. All services where correct time is essential should be ordered after this unit, but not pull it in. 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 "$time" facility.
 

SPECIAL USER UNITS

When systemd runs as a user instance, the following special units are available, which have similar definitions as their system counterparts: exit.target, default.target, shutdown.target, sockets.target, timers.target, paths.target, bluetooth.target, printer.target, smartcard.target, sound.target.  

SPECIAL PASSIVE USER UNITS

graphical-session.target

This target is active whenever any graphical session is running. It is used to stop user services which only apply to a graphical (X, Wayland, etc.) session when the session is terminated. Such services should have "PartOf=graphical-session.target" in their "[Unit]" section. A target for a particular session (e. g. gnome-session.target) starts and stops "graphical-session.target" with "BindsTo=graphical-session.target".

Which services are started by a session target is determined by the "Wants=" and "Requires=" dependencies. For services that can be enabled independently, symlinks in ".wants/" and ".requires/" should be used, see systemd.unit(5). Those symlinks should either be shipped in packages, or should be added dynamically after installation, for example using "systemctl add-wants", see systemctl(1).

Example 1. Nautilus as part of a GNOME session "gnome-session.target" pulls in Nautilus as top-level service:

[Unit]
Description=User systemd services for GNOME graphical session
Wants=nautilus.service
BindsTo=graphical-session.target

"nautilus.service" gets stopped when the session stops:

[Unit]
Description=Render the desktop icons with Nautilus
PartOf=graphical-session.target

[Service]
...

graphical-session-pre.target

This target contains services which set up the environment or global configuration of a graphical session, such as SSH/GPG agents (which need to export an environment variable into all desktop processes) or migration of obsolete d-conf keys after an OS upgrade (which needs to happen before starting any process that might use them). This target must be started before starting a graphical session like gnome-session.target.
 

SPECIAL SLICE UNITS

There are four ".slice" units which form the basis of the hierarchy for assignment of resources for services, users, and virtual machines or containers. See systemd.slice(7) for details about slice units.

-.slice

The root slice is the root of the slice hierarchy. It usually does not contain units directly, but may be used to set defaults for the whole tree.

system.slice

By default, all system services started by systemd are found in this slice.

user.slice

By default, all user processes and services started on behalf of the user, including the per-user systemd instance are found in this slice. This is pulled in by systemd-logind.service

machine.slice

By default, all virtual machines and containers registered with systemd-machined are found in this slice. This is pulled in by systemd-machined.service
 

SEE ALSO

systemd(1), systemd.unit(5), systemd.service(5), systemd.socket(5), systemd.target(5), systemd.slice(5), bootup(7), systemd-fstab-generator(8)  

NOTES

1.
Running Services After the Network is up
https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget
2.
Syslog Interface
https://www.freedesktop.org/wiki/Software/systemd/syslog


 

Index

NAME
SYNOPSIS
DESCRIPTION
SPECIAL SYSTEM UNITS
SPECIAL SYSTEM UNITS FOR DEVICES
SPECIAL PASSIVE SYSTEM UNITS
SPECIAL USER UNITS
SPECIAL PASSIVE USER UNITS
SPECIAL SLICE UNITS
SEE ALSO
NOTES

This document was created by man2html, using the manual pages.
Time: 04:45:57 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.GENERATOR

SYSTEMD.GENERATOR

Section: systemd.generator (7)
Updated:
Index Return to Main Contents
 

NAME

systemd.generator - systemd unit generators  

SYNOPSIS

/path/to/generator normal-dir early-dir late-dir

/run/systemd/system-generators/*
/etc/systemd/system-generators/*
/usr/local/lib/systemd/system-generators/*
/lib/systemd/system-generators/*

/run/systemd/user-generators/*
/etc/systemd/user-generators/*
/usr/local/lib/systemd/user-generators/*
/usr/lib/systemd/user-generators/*

 

DESCRIPTION

Generators are small executables that live in /lib/systemd/system-generators/ and other directories listed above. systemd(1) will execute those binaries very early at bootup and at configuration reload time --- before unit files are loaded. Generators may dynamically generate unit files (regular ones, instances as well as templates) and unit file .d/ drop-ins, or create symbolic links to unit files to add additional dependencies or instantiate existing templates, thus extending or overriding existing definitions. Their main purpose is to convert configuration files that are not native unit files dynamically into native unit files.

Generators are loaded from a set of paths determined during compilation, as listed above. System and user generators are loaded from directories with names ending in system-generators/ and user-generators/, respectively. Generators found in directories listed earlier override the ones with the same name in directories lower in the list. A symlink to /dev/null or an empty file can be used to mask a generator, thereby preventing it from running. Please note that the order of the two directories with the highest priority is reversed with respect to the unit load path, and generators in /run overwrite those in /etc.

After installing new generators or updating the configuration, systemctl daemon-reload may be executed. This will delete the previous configuration created by generators, re-run all generators, and cause systemd to reload units from disk. See systemctl(1) for more information.  

WRITING GENERATORS

Generators are invoked with three arguments: paths to runtime directories where generators can place their generated unit files or symlinks.

1. normal-dir

argv[1] may be used to override unit files in /usr, but not those in /run or in /etc. This means that unit files placed in this directory take precedence over vendor unit configuration but not over native user/administrator unit configuration.

2. early-dir

argv[2] may be used to override unit files in /usr, in /run and in /etc. This means that unit files placed in this directory take precedence over all configuration, both vendor and user/administrator.

3. late-dir

argv[3] may be used to extend the unit file tree without overriding any other unit files. Any native configuration files supplied by the vendor or user/administrator take precedence over the generated ones placed in this directory.

 

Notes

• All generators are executed in parallel. That means all executables are started at the very same time and need to be able to cope with this parallelism.

• Generators are run very early at boot and cannot rely on any external services. They may not talk to any other process. That includes simple things such as logging to syslog(3), or systemd itself (this means: no systemctl(1))! Non-essential file systems like /var and /home are mounted after generators have run. Generators can however rely on the most basic kernel functionality to be available, including a mounted /sys, /proc, /dev, /usr.

• Units written by generators are removed when the configuration is reloaded. That means the lifetime of the generated units is closely bound to the reload cycles of systemd itself.

• Generators should only be used to generate unit files and symlinks to them, not any other kind of configuration. Due to the lifecycle logic mentioned above, generators are not a good fit to generate dynamic configuration for other services. If you need to generate dynamic configuration for other services, do so in normal services you order before the service in question.

• Since syslog(3) is not available (see above), log messages have to be written to /dev/kmsg instead.

• It is a good idea to use the SourcePath= directive in generated unit files to specify the source configuration file you are generating the unit from. This makes things more easily understood by the user and also has the benefit that systemd can warn the user about configuration files that changed on disk but have not been read yet by systemd.

• Generators may write out dynamic unit files or just hook unit files into other units with the usual .wants/ or .requires/ symlinks. Often, it is nicer to simply instantiate a template unit file from /usr with a generator instead of writing out entirely dynamic unit files. Of course, this works only if a single parameter is to be used.

• If you are careful, you can implement generators in shell scripts. We do recommend C code however, since generators are executed synchronously and hence delay the entire boot if they are slow.

• Regarding overriding semantics: there are two rules we try to follow when thinking about the overriding semantics:

1. User configuration should override vendor configuration. This (mostly) means that stuff from /etc should override stuff from /usr.

2. Native configuration should override non-native configuration. This (mostly) means that stuff you generate should never override native unit files for the same purpose.

Of these two rules the first rule is probably the more important one and breaks the second one sometimes. Hence, when deciding whether to use argv[1], argv[2], or argv[3], your default choice should probably be argv[1].

• Instead of heading off now and writing all kind of generators for legacy configuration file formats, please think twice! It is often a better idea to just deprecate old stuff instead of keeping it artificially alive.
 

EXAMPLES

Example 1. systemd-fstab-generator

systemd-fstab-generator(8) converts /etc/fstab into native mount units. It uses argv[1] as location to place the generated unit files in order to allow the user to override /etc/fstab with her own native unit files, but also to ensure that /etc/fstab overrides any vendor default from /usr.

After editing /etc/fstab, the user should invoke systemctl daemon-reload. This will re-run all generators and cause systemd to reload units from disk. To actually mount new directories added to fstab, systemctl start /path/to/mountpoint or systemctl start local-fs.target may be used.

Example 2. systemd-system-update-generator

systemd-system-update-generator(8) temporarily redirects default.target to system-update.target, if a system update is scheduled. Since this needs to override the default user configuration for default.target, it uses argv[2]. For details about this logic, see systemd.offline-updates(7).

Example 3. Debugging a generator

dir=$(mktemp -d)
SYSTEMD_LOG_LEVEL=debug /lib/systemd/system-generators/systemd-fstab-generator \
        "$dir" "$dir" "$dir"
find $dir
 

SEE ALSO

systemd(1), systemd-cryptsetup-generator(8), systemd-debug-generator(8), systemd-fstab-generator(8), fstab(5), systemd-getty-generator(8), systemd-gpt-auto-generator(8), systemd-hibernate-resume-generator(8), systemd-rc-local-generator(8), systemd-system-update-generator(8), systemd-sysv-generator(8), systemd.unit(5), systemctl(1), systemd.environment-generator(7)


 

Index

NAME
SYNOPSIS
DESCRIPTION
WRITING GENERATORS
Notes
EXAMPLES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:45:58 GMT, September 16, 2022 Content-type: text/html; charset=UTF-8 Man page of SYSTEMD.DIRECTIVES

SYSTEMD.DIRECTIVES

Section: systemd.directives (7)
Updated:
Index Return to Main Contents
 

NAME

systemd.directives - Index of configuration directives  

UNIT DIRECTIVES

Directives for configuring units, used in unit files.

Accept=

systemd.socket(5)

AccuracySec=

systemd.timer(5)

After=

systemd.unit(5)

Alias=

systemd.unit(5)

AllowIsolate=

systemd.unit(5)

Also=

systemd.unit(5)

AmbientCapabilities=

systemd.exec(5)

AssertACPower=

systemd.unit(5)

AssertArchitecture=

systemd.unit(5)

AssertCapability=

systemd.unit(5)

AssertControlGroupController=

systemd.unit(5)

AssertDirectoryNotEmpty=

systemd.unit(5)

AssertFileIsExecutable=

systemd.unit(5)

AssertFileNotEmpty=

systemd.unit(5)

AssertFirstBoot=

systemd.unit(5)

AssertGroup=

systemd.unit(5)

AssertHost=

systemd.unit(5)

AssertKernelCommandLine=

systemd.unit(5)

AssertKernelVersion=

systemd.unit(5)

AssertNeedsUpdate=

systemd.unit(5)

AssertPathExists=

systemd.unit(5)

AssertPathExistsGlob=

systemd.unit(5)

AssertPathIsDirectory=

systemd.unit(5)

AssertPathIsMountPoint=

systemd.unit(5)

AssertPathIsReadWrite=

systemd.unit(5)

AssertPathIsSymbolicLink=

systemd.unit(5)

AssertSecurity=

systemd.unit(5)

AssertUser=

systemd.unit(5)

AssertVirtualization=

systemd.unit(5)

Backlog=

systemd.socket(5)

Before=

systemd.unit(5)

BindIPv6Only=

systemd.socket(5)

BindPaths=

systemd.exec(5)

BindReadOnlyPaths=

systemd.exec(5)

BindToDevice=

systemd.socket(5)

BindsTo=

systemd.unit(5)

BlockIOAccounting=

systemd.resource-control(5)

BlockIODeviceWeight=

systemd.resource-control(5)

BlockIOReadBandwidth=

systemd.resource-control(5)

BlockIOWeight=

systemd.resource-control(5)

BlockIOWriteBandwidth=

systemd.resource-control(5)

Broadcast=

systemd.socket(5)

BusName=

systemd.service(5)

CPUAccounting=

systemd.resource-control(5)

CPUQuota=

systemd.resource-control(5)

CPUShares=

systemd.resource-control(5)

CPUWeight=

systemd.resource-control(5)

CapabilityBoundingSet=

systemd.exec(5)

CollectMode=

systemd.unit(5)

ConditionACPower=

systemd.unit(5)

ConditionArchitecture=

systemd.unit(5)

ConditionCapability=

systemd.unit(5)

ConditionControlGroupController=

systemd.unit(5)

ConditionDirectoryNotEmpty=

systemd.unit(5)

ConditionFileIsExecutable=

systemd.unit(5)

ConditionFileNotEmpty=

systemd.unit(5)

ConditionFirstBoot=

systemd.unit(5)

ConditionGroup=

systemd.unit(5)

ConditionHost=

systemd.unit(5)

ConditionKernelCommandLine=

systemd.unit(5)

ConditionKernelVersion=

systemd.unit(5)

ConditionNeedsUpdate=

systemd.unit(5)

ConditionPathExists=

systemd.unit(5)

ConditionPathExistsGlob=

systemd.unit(5)

ConditionPathIsDirectory=

systemd.unit(5)

ConditionPathIsMountPoint=

systemd.unit(5)

ConditionPathIsReadWrite=

systemd.unit(5)

ConditionPathIsSymbolicLink=

systemd.unit(5)

ConditionSecurity=

systemd.unit(5)

ConditionUser=

systemd.unit(5)

ConditionVirtualization=

systemd.unit(5)

Conflicts=

systemd.unit(5)

DefaultDependencies=

systemd.unit(5)

DefaultInstance=

systemd.unit(5)

DeferAcceptSec=

systemd.socket(5)

Delegate=

systemd.resource-control(5)

Description=

systemd.unit(5)

DeviceAllow=

systemd.resource-control(5)

DevicePolicy=

systemd.resource-control(5)

DirectoryMode=

systemd.automount(5), systemd.mount(5), systemd.path(5), systemd.socket(5)

DirectoryNotEmpty=

systemd.path(5)

Documentation=

systemd.unit(5)

DynamicUser=

systemd.exec(5)

ExecReload=

systemd.service(5)

ExecStart=

systemd.service(5)

ExecStartPost=

systemd.service(5), systemd.socket(5)

ExecStartPre=

systemd.service(5), systemd.socket(5)

ExecStop=

systemd.service(5)

ExecStopPost=

systemd.service(5), systemd.socket(5)

ExecStopPre=

systemd.socket(5)

FailureAction=

systemd.unit(5)

FileDescriptorName=

systemd.socket(5)

FileDescriptorStoreMax=

systemd.service(5)

ForceUnmount=

systemd.mount(5)

FreeBind=

systemd.socket(5)

Group=

systemd.exec(5)

GuessMainPID=

systemd.service(5)

IOAccounting=

systemd.resource-control(5)

IODeviceWeight=

systemd.resource-control(5)

IOReadBandwidthMax=

systemd.resource-control(5)

IOReadIOPSMax=

systemd.resource-control(5)

IOWeight=

systemd.resource-control(5)

IOWriteBandwidthMax=

systemd.resource-control(5)

IOWriteIOPSMax=

systemd.resource-control(5)

IPAccounting=

systemd.resource-control(5)

IPAddressAllow=

systemd.resource-control(5)

IPAddressDeny=

systemd.resource-control(5)

IPTOS=

systemd.socket(5)

IPTTL=

systemd.socket(5)

IgnoreOnIsolate=

systemd.unit(5)

JobRunningTimeoutSec=

systemd.unit(5)

JobTimeoutAction=

systemd.unit(5)

JobTimeoutRebootArgument=

systemd.unit(5)

JobTimeoutSec=

systemd.unit(5)

JoinsNamespaceOf=

systemd.unit(5)

KeepAlive=

systemd.socket(5)

KeepAliveIntervalSec=

systemd.socket(5)

KeepAliveProbes=

systemd.socket(5)

KeepAliveTimeSec=

systemd.socket(5)

KillMode=

systemd.kill(5)

KillSignal=

systemd.kill(5)

LazyUnmount=

systemd.mount(5)

ListenDatagram=

systemd.socket(5)

ListenFIFO=

systemd.socket(5)

ListenMessageQueue=

systemd.socket(5)

ListenNetlink=

systemd.socket(5)

ListenSequentialPacket=

systemd.socket(5)

ListenSpecial=

systemd.socket(5)

ListenStream=

systemd.socket(5)

ListenUSBFunction=

systemd.socket(5)

MakeDirectory=

systemd.path(5)

Mark=

systemd.socket(5)

MaxConnections=

systemd.socket(5)

MaxConnectionsPerSource=

systemd.socket(5)

MemoryAccounting=

systemd.resource-control(5)

MemoryHigh=

systemd.resource-control(5)

MemoryLimit=

systemd.resource-control(5)

MemoryLow=

systemd.resource-control(5)

MemoryMax=

systemd.resource-control(5)

MemorySwapMax=

systemd.resource-control(5)

MessageQueueMaxMessages=

systemd.socket(5)

MessageQueueMessageSize=

systemd.socket(5)

MountAPIVFS=

systemd.exec(5)

NoDelay=

systemd.socket(5)

NoNewPrivileges=

systemd.exec(5)

NonBlocking=

systemd.service(5)

NotifyAccess=

systemd.service(5)

OnActiveSec=

systemd.timer(5)

OnBootSec=

systemd.timer(5)

OnCalendar=

systemd.timer(5)

OnFailure=

systemd.unit(5)

OnFailureJobMode=

systemd.unit(5)

OnStartupSec=

systemd.timer(5)

OnUnitActiveSec=

systemd.timer(5)

OnUnitInactiveSec=

systemd.timer(5)

Options=

systemd.mount(5), systemd.swap(5)

PAMName=

systemd.exec(5)

PIDFile=

systemd.service(5)

PartOf=

systemd.unit(5)

PassCredentials=

systemd.socket(5)

PassSecurity=

systemd.socket(5)

PathChanged=

systemd.path(5)

PathExists=

systemd.path(5)

PathExistsGlob=

systemd.path(5)

PathModified=

systemd.path(5)

PermissionsStartOnly=

systemd.service(5)

Persistent=

systemd.timer(5)

PipeSize=

systemd.socket(5)

Priority=

systemd.socket(5), systemd.swap(5)

PropagatesReloadTo=

systemd.unit(5)

RandomizedDelaySec=

systemd.timer(5)

RebootArgument=

systemd.unit(5)

ReceiveBuffer=

systemd.socket(5)

RefuseManualStart=

systemd.unit(5)

RefuseManualStop=

systemd.unit(5)

ReloadPropagatedFrom=

systemd.unit(5)

RemainAfterElapse=

systemd.timer(5)

RemainAfterExit=

systemd.service(5)

RemoveOnStop=

systemd.socket(5)

RequiredBy=

systemd.unit(5)

Requires=

systemd.unit(5)

RequiresMountsFor=

systemd.unit(5)

Requisite=

systemd.unit(5)

Restart=

systemd.service(5)

RestartForceExitStatus=

systemd.service(5)

RestartPreventExitStatus=

systemd.service(5)

RestartSec=

systemd.service(5)

ReusePort=

systemd.socket(5)

RootDirectory=

systemd.exec(5)

RootDirectoryStartOnly=

systemd.service(5)

RootImage=

systemd.exec(5)

RuntimeMaxSec=

systemd.service(5)

SELinuxContextFromNet=

systemd.socket(5)

SecureBits=

systemd.exec(5)

SendBuffer=

systemd.socket(5)

SendSIGHUP=

systemd.kill(5)

SendSIGKILL=

systemd.kill(5)

Service=

systemd.socket(5)

Slice=

systemd.resource-control(5)

SloppyOptions=

systemd.mount(5)

SmackLabel=

systemd.socket(5)

SmackLabelIPIn=

systemd.socket(5)

SmackLabelIPOut=

systemd.socket(5)

SocketGroup=

systemd.socket(5)

SocketMode=

systemd.socket(5)

SocketProtocol=

systemd.socket(5)

SocketUser=

systemd.socket(5)

Sockets=

systemd.service(5)

SourcePath=

systemd.unit(5)

StartLimitAction=

systemd.unit(5)

StartLimitBurst=

systemd.unit(5)

StartLimitIntervalSec=

systemd.unit(5)

StartupBlockIOWeight=

systemd.resource-control(5)

StartupCPUShares=

systemd.resource-control(5)

StartupCPUWeight=

systemd.resource-control(5)

StartupIOWeight=

systemd.resource-control(5)

StopWhenUnneeded=

systemd.unit(5)

SuccessAction=

systemd.unit(5)

SuccessExitStatus=

systemd.service(5)

SupplementaryGroups=

systemd.exec(5)

Symlinks=

systemd.socket(5)

TCPCongestion=

systemd.socket(5)

TasksAccounting=

systemd.resource-control(5)

TasksMax=

systemd.resource-control(5)

TimeoutIdleSec=

systemd.automount(5)

TimeoutSec=

systemd.mount(5), systemd.service(5), systemd.socket(5), systemd.swap(5)

TimeoutStartSec=

systemd.service(5)

TimeoutStopSec=

systemd.service(5)

Transparent=

systemd.socket(5)

TriggerLimitBurst=

systemd.socket(5)

TriggerLimitIntervalSec=

systemd.socket(5)

Type=

systemd.mount(5), systemd.service(5)

USBFunctionDescriptors=

systemd.service(5)

USBFunctionStrings=

systemd.service(5)

Unit=

systemd.path(5), systemd.timer(5)

User=

systemd.exec(5)

WakeSystem=

systemd.timer(5)

WantedBy=

systemd.unit(5)

Wants=

systemd.unit(5)

WatchdogSec=

systemd.service(5)

What=

systemd.mount(5), systemd.swap(5)

Where=

systemd.automount(5), systemd.mount(5)

WorkingDirectory=

systemd.exec(5)

Writable=

systemd.socket(5)
 

OPTIONS ON THE KERNEL COMMAND LINE

Kernel boot options for configuring the behaviour of the systemd process.

-b

kernel-command-line(7), systemd(1)

1

kernel-command-line(7), systemd(1)

2

kernel-command-line(7), systemd(1)

3

kernel-command-line(7), systemd(1)

4

kernel-command-line(7), systemd(1)

5

kernel-command-line(7), systemd(1)

S

kernel-command-line(7), systemd(1)

debug

kernel-command-line(7), systemd(1)

emergency

kernel-command-line(7), systemd(1)

fsck.mode=

kernel-command-line(7), systemd-fsck@.service(8)

fsck.repair=

kernel-command-line(7), systemd-fsck@.service(8)

fstab=

kernel-command-line(7), systemd-fstab-generator(8)

locale.LANG=

kernel-command-line(7), systemd(1)

locale.LANGUAGE=

kernel-command-line(7), systemd(1)

locale.LC_ADDRESS=

kernel-command-line(7), systemd(1)

locale.LC_COLLATE=

kernel-command-line(7), systemd(1)

locale.LC_CTYPE=

kernel-command-line(7), systemd(1)

locale.LC_IDENTIFICATION=

kernel-command-line(7), systemd(1)

locale.LC_MEASUREMENT=

kernel-command-line(7), systemd(1)

locale.LC_MESSAGES=

kernel-command-line(7), systemd(1)

locale.LC_MONETARY=

kernel-command-line(7), systemd(1)

locale.LC_NAME=

kernel-command-line(7), systemd(1)

locale.LC_NUMERIC=

kernel-command-line(7), systemd(1)

locale.LC_PAPER=

kernel-command-line(7), systemd(1)

locale.LC_TELEPHONE=

kernel-command-line(7), systemd(1)

locale.LC_TIME=

kernel-command-line(7), systemd(1)

luks.crypttab=

kernel-command-line(7), systemd-cryptsetup-generator(8)

luks.key=

kernel-command-line(7), systemd-cryptsetup-generator(8)

luks.name=

kernel-command-line(7), systemd-cryptsetup-generator(8)

luks.options=

kernel-command-line(7), systemd-cryptsetup-generator(8)

luks.uuid=

kernel-command-line(7), systemd-cryptsetup-generator(8)

luks=

kernel-command-line(7), systemd-cryptsetup-generator(8)

modules_load=

kernel-command-line(7), systemd-modules-load.service(8)

mount.usr=

kernel-command-line(7), systemd-fstab-generator(8)

mount.usrflags=

kernel-command-line(7), systemd-fstab-generator(8)

mount.usrfstype=

kernel-command-line(7), systemd-fstab-generator(8)

net.ifnames=

kernel-command-line(7), systemd-udevd.service(8)

plymouth.enable=

kernel-command-line(7)

quiet

kernel-command-line(7), systemd(1)

quotacheck.mode=

kernel-command-line(7), systemd-quotacheck.service(8)

rd.emergency

kernel-command-line(7), systemd(1)

rd.fstab=

kernel-command-line(7), systemd-fstab-generator(8)

rd.luks.crypttab=

kernel-command-line(7), systemd-cryptsetup-generator(8)

rd.luks.key=

kernel-command-line(7), systemd-cryptsetup-generator(8)

rd.luks.name=

kernel-command-line(7), systemd-cryptsetup-generator(8)

rd.luks.options=

kernel-command-line(7), systemd-cryptsetup-generator(8)

rd.luks.uuid=

kernel-command-line(7), systemd-cryptsetup-generator(8)

rd.luks=

kernel-command-line(7), systemd-cryptsetup-generator(8)

rd.modules_load=

kernel-command-line(7), systemd-modules-load.service(8)

rd.rescue

kernel-command-line(7), systemd(1)

rd.systemd.gpt_auto=

kernel-command-line(7)

rd.systemd.unit=

kernel-command-line(7), systemd(1)

rd.systemd.verity=

kernel-command-line(7), systemd-veritysetup-generator(8)

rd.udev.children_max=

kernel-command-line(7), systemd-udevd.service(8)

rd.udev.event_timeout=

kernel-command-line(7), systemd-udevd.service(8)

rd.udev.exec_delay=

kernel-command-line(7), systemd-udevd.service(8)

rd.udev.log_priority=

kernel-command-line(7), systemd-udevd.service(8)

rescue

kernel-command-line(7), systemd(1)

resume=

kernel-command-line(7), systemd-hibernate-resume-generator(8)

ro

kernel-command-line(7)

root=

kernel-command-line(7), systemd-fstab-generator(8)

rootflags=

kernel-command-line(7), systemd-fstab-generator(8)

rootfstype=

kernel-command-line(7), systemd-fstab-generator(8)

roothash=

kernel-command-line(7), systemd-veritysetup-generator(8)

rw

kernel-command-line(7)

s

kernel-command-line(7), systemd(1)

single

kernel-command-line(7), systemd(1)

systemd.confirm_spawn

kernel-command-line(7), systemd(1)

systemd.crash_chvt

kernel-command-line(7), systemd(1)

systemd.crash_reboot

kernel-command-line(7), systemd(1)

systemd.crash_shell

kernel-command-line(7), systemd(1)

systemd.debug_shell

kernel-command-line(7)

systemd.default_standard_error=

kernel-command-line(7), systemd(1)

systemd.default_standard_output=

kernel-command-line(7), systemd(1)

systemd.default_timeout_start_sec=

kernel-command-line(7)

systemd.dump_core

kernel-command-line(7), systemd(1)

systemd.firstboot=

kernel-command-line(7)

systemd.gpt_auto=

kernel-command-line(7)

systemd.journald.forward_to_console=

kernel-command-line(7), systemd-journald.service(8)

systemd.journald.forward_to_kmsg=

kernel-command-line(7), systemd-journald.service(8)

systemd.journald.forward_to_syslog=

kernel-command-line(7), systemd-journald.service(8)

systemd.journald.forward_to_wall=

kernel-command-line(7), systemd-journald.service(8)

systemd.legacy_systemd_cgroup_controller

kernel-command-line(7), systemd(1)

systemd.log_color

kernel-command-line(7), systemd(1)

systemd.log_level=

kernel-command-line(7), systemd(1)

systemd.log_location=

kernel-command-line(7), systemd(1)

systemd.log_target=

kernel-command-line(7), systemd(1)

systemd.machine_id=

kernel-command-line(7), systemd(1)

systemd.mask=

kernel-command-line(7)

systemd.restore_state=

kernel-command-line(7), systemd-backlight@.service(8), systemd-rfkill.service(8)

systemd.service_watchdogs

kernel-command-line(7)

systemd.service_watchdogs=

systemd(1)

systemd.setenv=

kernel-command-line(7), systemd(1)

systemd.show_status

kernel-command-line(7), systemd(1)

systemd.unified_cgroup_hierarchy

kernel-command-line(7), systemd(1)

systemd.unit=

kernel-command-line(7), systemd(1)

systemd.verity=

kernel-command-line(7), systemd-veritysetup-generator(8)

systemd.verity_root_data=

kernel-command-line(7), systemd-veritysetup-generator(8)

systemd.verity_root_hash=

kernel-command-line(7), systemd-veritysetup-generator(8)

systemd.volatile=

kernel-command-line(7), systemd-fstab-generator(8)

systemd.wants=

kernel-command-line(7)

systemd.watchdog_device=

kernel-command-line(7)

udev.children_max=

kernel-command-line(7), systemd-udevd.service(8)

udev.event_timeout=

kernel-command-line(7), systemd-udevd.service(8)

udev.exec_delay=

kernel-command-line(7), systemd-udevd.service(8)

udev.log_priority=

kernel-command-line(7), systemd-udevd.service(8)

vconsole.font=

kernel-command-line(7)

vconsole.font_map=

kernel-command-line(7)

vconsole.font_unimap=

kernel-command-line(7)

vconsole.keymap=

kernel-command-line(7)

vconsole.keymap_toggle=

kernel-command-line(7)
 

ENVIRONMENT VARIABLES

Environment variables understood by the systemd manager and other programs.

$EXIT_CODE

systemd.exec(5)

$EXIT_STATUS

systemd.exec(5)

$HOME

systemd.exec(5)

$INVOCATION_ID

systemd.exec(5)

$JOURNAL_STREAM

systemd.exec(5)

$LANG

systemd.exec(5)

$LISTEN_FDNAMES

sd_listen_fds(3), systemd(1), systemd-socket-activate(1), systemd.exec(5)

$LISTEN_FDS

sd_listen_fds(3), systemd(1), systemd-socket-activate(1), systemd.exec(5)

$LISTEN_PID

sd_listen_fds(3), systemd(1), systemd-socket-activate(1), systemd.exec(5)

$LOGNAME

systemd.exec(5)

$MAINPID

systemd.exec(5)

$MANAGERPID

systemd.exec(5)

$NOTIFY_SOCKET

sd_notify(3), systemd(1), systemd.exec(5)

$PATH

systemd.exec(5)

$PREVLEVEL

runlevel(8)

$RUNLEVEL

runlevel(8)

$SERVICE_RESULT

systemd.exec(5)

$SHELL

systemd.exec(5)

$SYSTEMD_COLORS

systemd(1)

$SYSTEMD_EDITOR

systemctl(1)

$SYSTEMD_LESS

journalctl(1), localectl(1), loginctl(1), machinectl(1), systemd-analyze(1), timedatectl(1)

$SYSTEMD_LESSCHARSET

journalctl(1), localectl(1), loginctl(1), machinectl(1), systemd-analyze(1), timedatectl(1)

$SYSTEMD_LOG_COLOR

systemd(1), systemd-socket-activate(1)

$SYSTEMD_LOG_LEVEL

systemd(1), systemd-socket-activate(1)

$SYSTEMD_LOG_LOCATION

systemd(1), systemd-socket-activate(1)

$SYSTEMD_LOG_TARGET

systemd(1), systemd-socket-activate(1)

$SYSTEMD_PAGER

journalctl(1), localectl(1), loginctl(1), machinectl(1), systemd-analyze(1), timedatectl(1)

$SYSTEMD_SYSVINIT_PATH

systemd(1)

$SYSTEMD_SYSVRCND_PATH

systemd(1)

$SYSTEMD_UNIT_PATH

systemd(1)

$TERM

systemd.exec(5)

$USER

systemd.exec(5)

$WATCHDOG_PID

sd_watchdog_enabled(3), systemd.exec(5)

$WATCHDOG_USEC

sd_watchdog_enabled(3), systemd.exec(5)

$XDG_CONFIG_DIRS

systemd(1)

$XDG_CONFIG_HOME

systemd(1)

$XDG_DATA_DIRS

systemd(1)

$XDG_DATA_HOME

systemd(1)

$XDG_RUNTIME_DIR

pam_systemd(8), systemd.exec(5)

$XDG_SEAT

pam_systemd(8), systemd.exec(5)

$XDG_SESSION_CLASS

pam_systemd(8)

$XDG_SESSION_DESKTOP

pam_systemd(8)

$XDG_SESSION_ID

pam_systemd(8), systemd.exec(5)

$XDG_SESSION_TYPE

pam_systemd(8)

$XDG_VTNR

pam_systemd(8), systemd.exec(5)
 

UDEV DIRECTIVES

Directives for configuring systemd units through the udev database.

$$

udev(7)

$attr{file}

udev(7)

$devnode

udev(7)

$devpath

udev(7)

$driver

udev(7)

$env{key}

udev(7)

$id

udev(7)

$kernel

udev(7)

$links

udev(7)

$major

udev(7)

$minor

udev(7)

$name

udev(7)

$number

udev(7)

$parent

udev(7)

$result

udev(7)

$root

udev(7)

$sys

udev(7)

%%

udev(7)

%E{key}

udev(7)

%M

udev(7)

%N

udev(7)

%P

udev(7)

%S

udev(7)

%b

udev(7)

%c

udev(7)

%k

udev(7)

%m

udev(7)

%n

udev(7)

%p

udev(7)

%r

udev(7)

%s{file}

udev(7)

ACTION

udev(7)

ATTRS{filename}

udev(7)

ATTR{filename}

udev(7)

DEVPATH

udev(7)

DRIVER

udev(7)

DRIVERS

udev(7)

ENV{key}

udev(7)

GOTO

udev(7)

GROUP

udev(7)

ID_MODEL=

systemd.device(5)

ID_MODEL_FROM_DATABASE=

systemd.device(5)

IMPORT{type}

udev(7)

KERNEL

udev(7)

KERNELS

udev(7)

LABEL

udev(7)

MODE

udev(7)

NAME

udev(7)

OPTIONS

udev(7)

OWNER

udev(7)

PROGRAM

udev(7)

RESULT

udev(7)

RUN{type}

udev(7)

SECLABEL{module}

udev(7)

SUBSYSTEM

udev(7)

SUBSYSTEMS

udev(7)

SYMLINK

udev(7)

SYSCTL{kernel parameter}

udev(7)

SYSTEMD_ALIAS=

systemd.device(5)

SYSTEMD_MOUNT_OPTIONS=

systemd-mount(1)

SYSTEMD_MOUNT_WHERE=

systemd-mount(1)

SYSTEMD_READY=

systemd.device(5)

SYSTEMD_USER_WANTS=

systemd.device(5)

SYSTEMD_WANTS=

systemd.device(5)

TAG

udev(7)

TAGS

udev(7)

TEST{octal mode mask}

udev(7)

link_priority=

udev(7)

nowatch

udev(7)

static_node=

udev(7)

string_escape=

udev(7)

watch

udev(7)
 

NETWORK DIRECTIVES

Directives for configuring network links through the net-setup-link udev builtin and networks through systemd-networkd.

ARP=

systemd.network(5)

ARPAllTargets=

systemd.netdev(5)

ARPIPTargets=

systemd.netdev(5)

ARPIntervalSec=

systemd.netdev(5)

ARPValidate=

systemd.netdev(5)

ActiveSlave=

systemd.network(5)

AdSelect=

systemd.netdev(5)

Address=

systemd.network(5)

AddressAutoconfiguration=

systemd.network(5)

AgeingTimeSec=

systemd.netdev(5)

Alias=

systemd.link(5)

AllSlavesActive=

systemd.netdev(5)

AllowLocalRemote=

systemd.netdev(5)

AllowPortToBeRoot=

systemd.network(5)

AllowedIPs=

systemd.netdev(5)

Anonymize=

systemd.network(5)

Architecture=

systemd.link(5), systemd.netdev(5), systemd.network(5)

AutoJoin=

systemd.network(5)

AutoNegotiation=

systemd.link(5)

BindCarrier=

systemd.network(5)

BitsPerSecond=

systemd.link(5)

Bond=

systemd.network(5)

Bridge=

systemd.network(5)

Broadcast=

systemd.network(5)

Cache=

resolved.conf(5)

ClientIdentifier=

systemd.network(5)

ConfigureWithoutCarrier=

systemd.network(5)

CopyDSCP=

systemd.netdev(5)

Cost=

systemd.network(5)

DHCP=

systemd.network(5)

DHCPServer=

systemd.network(5)

DNS=

resolved.conf(5), systemd.network(5)

DNSLifetimeSec=

systemd.network(5)

DNSSEC=

resolved.conf(5), systemd.network(5)

DNSSECNegativeTrustAnchors=

systemd.network(5)

DNSStubListener=

resolved.conf(5)

DUIDRawData=

networkd.conf(5), systemd.network(5)

DUIDType=

networkd.conf(5), systemd.network(5)

DefaultLeaseTimeSec=

systemd.network(5)

DefaultPVID=

systemd.netdev(5)

Description=

systemd.link(5), systemd.netdev(5), systemd.network(5)

Destination=

systemd.network(5)

DestinationPort=

systemd.netdev(5)

DiscoverPathMTU=

systemd.netdev(5)

Domains=

resolved.conf(5), systemd.network(5)

DownDelaySec=

systemd.netdev(5)

Driver=

systemd.link(5), systemd.network(5)

Duplex=

systemd.link(5)

DuplicateAddressDetection=

systemd.network(5)

EgressUntagged=

systemd.network(5)

EmitDNS=

systemd.network(5)

EmitDomains=

systemd.network(5)

EmitLLDP=

systemd.network(5)

EmitNTP=

systemd.network(5)

EmitRouter=

systemd.network(5)

EmitTimezone=

systemd.network(5)

EncapsulationLimit=

systemd.netdev(5)

Endpoint=

systemd.netdev(5)

FDBAgeingSec=

systemd.netdev(5)

FailOverMACPolicy=

systemd.netdev(5)

FallbackDNS=

resolved.conf(5)

FallbackNTP=

timesyncd.conf(5)

FastLeave=

systemd.network(5)

FirewallMark=

systemd.network(5)

Flags=

systemd.netdev(5)

FlowLabel=

systemd.netdev(5)

ForwardDelaySec=

systemd.netdev(5)

From=

systemd.network(5)

FwMark=

systemd.netdev(5)

GVRP=

systemd.netdev(5)

Gateway=

systemd.network(5)

GatewayOnlink=

systemd.network(5)

GenericReceiveOffload=

systemd.link(5)

GenericSegmentationOffload=

systemd.link(5)

GratuitousARP=

systemd.netdev(5)

Group=

systemd.netdev(5)

GroupForwardMask=

systemd.netdev(5)

GroupPolicyExtension=

systemd.netdev(5)

HairPin=

systemd.network(5)

HelloTimeSec=

systemd.netdev(5)

HomeAddress=

systemd.network(5)

Host=

systemd.link(5), systemd.netdev(5), systemd.network(5)

Hostname=

systemd.network(5)

IAID=

systemd.network(5)

IPForward=

systemd.network(5)

IPMasquerade=

systemd.network(5)

IPv4LLRoute=

systemd.network(5)

IPv4ProxyARP=

systemd.network(5)

IPv6AcceptRA=

systemd.network(5)

IPv6DuplicateAddressDetection=

systemd.network(5)

IPv6FlowLabel=

systemd.netdev(5)

IPv6HopLimit=

systemd.network(5)

IPv6MTUBytes=

systemd.network(5)

IPv6Preference=

systemd.network(5)

IPv6PrefixDelegation=

systemd.network(5)

IPv6PrivacyExtensions=

systemd.network(5)

IPv6ProxyNDP=

systemd.network(5)

IPv6ProxyNDPAddress=

systemd.network(5)

IPv6Token=

systemd.network(5)

Id=

systemd.netdev(5)

IgnoreCarrierLoss=

systemd.network(5)

IncomingInterface=

systemd.network(5)

Independent=

systemd.netdev(5)

InitialAdvertisedReceiveWindow=

systemd.network(5)

InitialCongestionWindow=

systemd.network(5)

InputKey=

systemd.netdev(5)

KeepConfiguration=

systemd.network(5)

KernelCommandLine=

systemd.link(5), systemd.netdev(5), systemd.network(5)

KernelVersion=

systemd.link(5), systemd.netdev(5), systemd.network(5)

Key=

systemd.netdev(5)

Kind=

systemd.netdev(5)

L2MissNotification=

systemd.netdev(5)

L3MissNotification=

systemd.netdev(5)

LACPTransmitRate=

systemd.netdev(5)

LLDP=

systemd.network(5)

LLMNR=

resolved.conf(5), systemd.network(5)

Label=

systemd.network(5)

LargeReceiveOffload=

systemd.link(5)

LearnPacketIntervalSec=

systemd.netdev(5)

LinkLocalAddressing=

systemd.network(5)

ListenPort=

systemd.netdev(5), systemd.network(5)

Local=

systemd.netdev(5)

LooseBinding=

systemd.netdev(5)

MACAddress=

systemd.link(5), systemd.netdev(5), systemd.network(5)

MACAddressPolicy=

systemd.link(5)

MACVLAN=

systemd.network(5)

MIIMonitorSec=

systemd.netdev(5)

MTUBytes=

systemd.link(5), systemd.netdev(5), systemd.network(5)

MVRP=

systemd.netdev(5)

MacLearning=

systemd.netdev(5)

ManageTemporaryAddress=

systemd.network(5)

Managed=

systemd.network(5)

MaxAgeSec=

systemd.netdev(5)

MaxLeaseTimeSec=

systemd.network(5)

MaximumFDBEntries=

systemd.netdev(5)

Metric=

systemd.network(5)

MinLinks=

systemd.netdev(5)

Mode=

systemd.netdev(5)

MultiQueue=

systemd.netdev(5)

MulticastDNS=

resolved.conf(5), systemd.network(5)

MulticastQuerier=

systemd.netdev(5)

MulticastSnooping=

systemd.netdev(5)

NTP=

systemd.network(5), timesyncd.conf(5)

Name=

systemd.dnssd(5), systemd.link(5), systemd.netdev(5), systemd.network(5)

NamePolicy=

systemd.link(5)

OnLink=

systemd.network(5)

OneQueue=

systemd.netdev(5)

OriginalName=

systemd.link(5)

OtherInformation=

systemd.network(5)

OutgoingInterface=

systemd.network(5)

OutputKey=

systemd.netdev(5)

PVID=

systemd.network(5)

PacketInfo=

systemd.netdev(5)

PacketsPerSlave=

systemd.netdev(5)

Path=

systemd.link(5), systemd.network(5)

Peer=

systemd.netdev(5), systemd.network(5)

PersistentKeepalive=

systemd.netdev(5)

PollIntervalMaxSec=

timesyncd.conf(5)

PollIntervalMinSec=

timesyncd.conf(5)

PoolOffset=

systemd.network(5)

PoolSize=

systemd.network(5)

Port=

systemd.dnssd(5), systemd.link(5)

PortRange=

systemd.netdev(5)

PreferredLifetime=

systemd.network(5)

PreferredLifetimeSec=

systemd.network(5)

PreferredSource=

systemd.network(5)

Prefix=

systemd.network(5)

PrefixRoute=

systemd.network(5)

PresharedKey=

systemd.netdev(5)

PrimaryReselectPolicy=

systemd.netdev(5)

PrimarySlave=

systemd.network(5)

Priority=

systemd.dnssd(5), systemd.netdev(5), systemd.network(5)

PrivateKey=

systemd.netdev(5)

Protocol=

systemd.network(5)

PublicKey=

systemd.netdev(5)

QuickAck=

systemd.network(5)

RapidCommit=

systemd.network(5)

ReduceARPProxy=

systemd.netdev(5)

Remote=

systemd.netdev(5)

RemoteChecksumRx=

systemd.netdev(5)

RemoteChecksumTx=

systemd.netdev(5)

ReorderHeader=

systemd.netdev(5)

RequestBroadcast=

systemd.network(5)

RequiredForOnline=

systemd.network(5)

ResendIGMP=

systemd.netdev(5)

RootDistanceMaxSec=

timesyncd.conf(5)

RouteMetric=

systemd.network(5)

RouteShortCircuit=

systemd.netdev(5)

RouteTable=

systemd.network(5)

RouterLifetimeSec=

systemd.network(5)

RouterPreference=

systemd.network(5)

STP=

systemd.netdev(5)

Scope=

systemd.network(5)

SendHostname=

systemd.network(5)

Source=

systemd.network(5)

TCP6SegmentationOffload=

systemd.link(5)

TCPSegmentationOffload=

systemd.link(5)

TOS=

systemd.netdev(5)

TTL=

systemd.netdev(5)

Table=

systemd.network(5)

Timezone=

systemd.network(5)

To=

systemd.network(5)

TransmitHashPolicy=

systemd.netdev(5)

Tunnel=

systemd.network(5)

TxtData=

systemd.dnssd(5)

TxtText=

systemd.dnssd(5)

Type=

systemd.dnssd(5), systemd.link(5), systemd.network(5)

TypeOfService=

systemd.network(5)

UDP6ZeroChecksumRx=

systemd.netdev(5)

UDP6ZeroChecksumTx=

systemd.netdev(5)

UDPChecksum=

systemd.netdev(5)

UDPSegmentationOffload=

systemd.link(5)

UnicastFlood=

systemd.network(5)

Unmanaged=

systemd.network(5)

UpDelaySec=

systemd.netdev(5)

UseBPDU=

systemd.network(5)

UseDNS=

systemd.network(5)

UseDomains=

systemd.network(5)

UseGateway=

systemd.network(5)

UseHostname=

systemd.network(5)

UseMTU=

systemd.network(5)

UseNTP=

systemd.network(5)

UseRoutes=

systemd.network(5)

UseTimezone=

systemd.network(5)

User=

systemd.netdev(5)

VLAN=

systemd.network(5)

VLANFiltering=

systemd.netdev(5)

VLANId=

systemd.network(5)

VNetHeader=

systemd.netdev(5)

VRF=

systemd.network(5)

VXLAN=

systemd.network(5)

ValidLifetimeSec=

systemd.network(5)

VendorClassIdentifier=

systemd.network(5)

Virtualization=

systemd.link(5), systemd.netdev(5), systemd.network(5)

WakeOnLan=

systemd.link(5)

Weight=

systemd.dnssd(5)
 

JOURNAL FIELDS

Fields in the journal events with a well known meaning.

CODE_FILE=

systemd.journal-fields(7)

CODE_FUNC=

systemd.journal-fields(7)

CODE_LINE=

systemd.journal-fields(7)

COREDUMP_UNIT=

systemd.journal-fields(7)

COREDUMP_USER_UNIT=

systemd.journal-fields(7)

ERRNO=

systemd.journal-fields(7)

MESSAGE=

systemd.journal-fields(7)

MESSAGE_ID=

systemd.journal-fields(7)

OBJECT_AUDIT_LOGINUID=

systemd.journal-fields(7)

OBJECT_AUDIT_SESSION=

systemd.journal-fields(7)

OBJECT_CMDLINE=

systemd.journal-fields(7)

OBJECT_COMM=

systemd.journal-fields(7)

OBJECT_EXE=

systemd.journal-fields(7)

OBJECT_GID=

systemd.journal-fields(7)

OBJECT_PID=

systemd.journal-fields(7)

OBJECT_SYSTEMD_CGROUP=

systemd.journal-fields(7)

OBJECT_SYSTEMD_OWNER_UID=

systemd.journal-fields(7)

OBJECT_SYSTEMD_SESSION=

systemd.journal-fields(7)

OBJECT_SYSTEMD_UNIT=

systemd.journal-fields(7)

OBJECT_SYSTEMD_USER_UNIT=

systemd.journal-fields(7)

OBJECT_UID=

systemd.journal-fields(7)

PRIORITY=

systemd.journal-fields(7)

SYSLOG_FACILITY=

systemd.journal-fields(7)

SYSLOG_IDENTIFIER=

systemd.journal-fields(7)

SYSLOG_PID=

systemd.journal-fields(7)

_AUDIT_LOGINUID=

systemd.journal-fields(7)

_AUDIT_SESSION=

systemd.journal-fields(7)

_BOOT_ID=

systemd.journal-fields(7)

_CAP_EFFECTIVE=

systemd.journal-fields(7)

_CMDLINE=

systemd.journal-fields(7)

_COMM=

systemd.journal-fields(7)

_EXE=

systemd.journal-fields(7)

_GID=

systemd.journal-fields(7)

_HOSTNAME=

systemd.journal-fields(7)

_KERNEL_DEVICE=

systemd.journal-fields(7)

_KERNEL_SUBSYSTEM=

systemd.journal-fields(7)

_LINE_BREAK=

systemd.journal-fields(7)

_MACHINE_ID=

systemd.journal-fields(7)

_PID=

systemd.journal-fields(7)

_SELINUX_CONTEXT=

systemd.journal-fields(7)

_SOURCE_REALTIME_TIMESTAMP=

systemd.journal-fields(7)

_STREAM_ID=

systemd.journal-fields(7)

_SYSTEMD_CGROUP=

systemd.journal-fields(7)

_SYSTEMD_INVOCATION_ID=

systemd.journal-fields(7)

_SYSTEMD_OWNER_UID=

systemd.journal-fields(7)

_SYSTEMD_SESSION=

systemd.journal-fields(7)

_SYSTEMD_SLICE=

systemd.journal-fields(7)

_SYSTEMD_UNIT=

systemd.journal-fields(7)

_SYSTEMD_USER_UNIT=

systemd.journal-fields(7)

_TRANSPORT=

systemd.journal-fields(7)

_UDEV_DEVLINK=

systemd.journal-fields(7)

_UDEV_DEVNODE=

systemd.journal-fields(7)

_UDEV_SYSNAME=

systemd.journal-fields(7)

_UID=

systemd.journal-fields(7)

__CURSOR=

systemd.journal-fields(7)

__MONOTONIC_TIMESTAMP=

systemd.journal-fields(7)

__REALTIME_TIMESTAMP=

systemd.journal-fields(7)
 

PAM CONFIGURATION DIRECTIVES

Directives for configuring PAM behaviour.

class=

pam_systemd(8)

debug

pam_systemd(8)

type=

pam_systemd(8)
 

/ETC/CRYPTTAB AND /ETC/FSTAB OPTIONS

Options which influence mounted filesystems and encrypted volumes.

_netdev

crypttab(5), systemd.mount(5)

auto

systemd.mount(5), systemd.swap(5)

cipher=

crypttab(5)

discard

crypttab(5)

hash=

crypttab(5)

header=

crypttab(5)

key-slot=

crypttab(5)

keyfile-offset=

crypttab(5)

keyfile-size=

crypttab(5)

luks

crypttab(5)

noauto

crypttab(5), systemd.mount(5), systemd.swap(5)

nofail

crypttab(5), systemd.mount(5), systemd.swap(5)

offset=

crypttab(5)

plain

crypttab(5)

read-only

crypttab(5)

readonly

crypttab(5)

sector-size=

crypttab(5)

size=

crypttab(5)

skip=

crypttab(5)

swap

crypttab(5)

tcrypt

crypttab(5)

tcrypt-hidden

crypttab(5)

tcrypt-keyfile=

crypttab(5)

tcrypt-system

crypttab(5)

tcrypt-veracrypt

crypttab(5)

timeout=

crypttab(5)

tmp

crypttab(5)

tries=

crypttab(5)

verify

crypttab(5)

x-initrd.mount

systemd.mount(5)

x-systemd.after=

systemd.mount(5)

x-systemd.automount

systemd.mount(5)

x-systemd.before=

systemd.mount(5)

x-systemd.device-bound

systemd.mount(5)

x-systemd.device-timeout=

crypttab(5), systemd.mount(5)

x-systemd.growfs

systemd.mount(5)

x-systemd.idle-timeout=

systemd.mount(5)

x-systemd.makefs

systemd.mount(5)

x-systemd.mount-timeout=

systemd.mount(5)

x-systemd.requires-mounts-for=

systemd.mount(5)

x-systemd.requires=

systemd.mount(5)
 

SYSTEM MANAGER DIRECTIVES

Directives for configuring the behaviour of the systemd process.

CPUAffinity=

systemd-system.conf(5)

CapabilityBoundingSet=

systemd-system.conf(5)

CrashChangeVT=

systemd-system.conf(5)

CrashReboot=

systemd-system.conf(5)

CrashShell=

systemd-system.conf(5)

CtrlAltDelBurstAction=

systemd-system.conf(5)

DefaultBlockIOAccounting=

systemd-system.conf(5)

DefaultCPUAccounting=

systemd-system.conf(5)

DefaultEnvironment=

systemd-system.conf(5)

DefaultIPAccounting=

systemd-system.conf(5)

DefaultLimitAS=

systemd-system.conf(5)

DefaultLimitCORE=

systemd-system.conf(5)

DefaultLimitCPU=

systemd-system.conf(5)

DefaultLimitDATA=

systemd-system.conf(5)

DefaultLimitFSIZE=

systemd-system.conf(5)

DefaultLimitLOCKS=

systemd-system.conf(5)

DefaultLimitMEMLOCK=

systemd-system.conf(5)

DefaultLimitMSGQUEUE=

systemd-system.conf(5)

DefaultLimitNICE=

systemd-system.conf(5)

DefaultLimitNOFILE=

systemd-system.conf(5)

DefaultLimitNPROC=

systemd-system.conf(5)

DefaultLimitRSS=

systemd-system.conf(5)

DefaultLimitRTPRIO=

systemd-system.conf(5)

DefaultLimitRTTIME=

systemd-system.conf(5)

DefaultLimitSIGPENDING=

systemd-system.conf(5)

DefaultLimitSTACK=

systemd-system.conf(5)

DefaultMemoryAccounting=

systemd-system.conf(5)

DefaultRestartSec=

systemd-system.conf(5)

DefaultStandardError=

systemd-system.conf(5)

DefaultStandardOutput=

systemd-system.conf(5)

DefaultStartLimitBurst=

systemd-system.conf(5)

DefaultStartLimitIntervalSec=

systemd-system.conf(5)

DefaultTasksAccounting=

systemd-system.conf(5)

DefaultTasksMax=

systemd-system.conf(5)

DefaultTimeoutStartSec=

systemd-system.conf(5)

DefaultTimeoutStopSec=

systemd-system.conf(5)

DefaultTimerAccuracySec=

systemd-system.conf(5)

DumpCore=

systemd-system.conf(5)

HibernateDelaySec=

systemd-sleep.conf(5)

HibernateMode=

systemd-sleep.conf(5)

HibernateState=

systemd-sleep.conf(5)

HybridSleepMode=

systemd-sleep.conf(5)

HybridSleepState=

systemd-sleep.conf(5)

JoinControllers=

systemd-system.conf(5)

LogColor=

systemd-system.conf(5)

LogLevel=

systemd-system.conf(5)

LogLocation=

systemd-system.conf(5)

LogTarget=

systemd-system.conf(5)

RuntimeWatchdogSec=

systemd-system.conf(5)

ShowStatus=

systemd-system.conf(5)

ShutdownWatchdogSec=

systemd-system.conf(5)

SuspendMode=

systemd-sleep.conf(5)

SuspendState=

systemd-sleep.conf(5)

SystemCallArchitectures=

systemd-system.conf(5)

TimerSlackNSec=

systemd-system.conf(5)

WatchdogDevice=

systemd-system.conf(5)
 

COMMAND LINE OPTIONS

Command-line options accepted by programs in the systemd suite.

--accept

systemd-socket-activate(1)

--accept-cached

systemd-ask-password(1)

--acquired

busctl(1)

--action=

udevadm(8)

--activatable

busctl(1)

--address=

busctl(1)

--adjust-system-clock

timedatectl(1)

--after

systemctl(1)

--after-cursor=

journalctl(1), systemd-journal-upload(8)

--all

journalctl(1), loginctl(1), machinectl(1), networkctl(1), systemctl(1), systemd-cgls(1)

--allow-interactive-authorization=

busctl(1)

--as-pid2

systemd-nspawn(1)

--attr-match=

udevadm(8)

--attr-nomatch=

udevadm(8)

--attribute-walk

udevadm(8)

--augment-creds=

busctl(1)

--auto-start=

busctl(1)

--automount-property=

systemd-mount(1)

--automount=

systemd-mount(1)

--batch

systemd-cgtop(1)

--before

systemctl(1)

--bind-device=

systemd-mount(1)

--bind-ro=

systemd-nspawn(1)

--bind=

systemd-nspawn(1)

--boot

systemd-nspawn(1), systemd-tmpfiles(8)

--boot=

journalctl(1)

--booted

systemd-notify(1)

--capability=

systemd-nspawn(1)

--case-sensitive[=BOOLEAN]

journalctl(1)

--catalog

journalctl(1)

--cert=

systemd-journal-gatewayd.service(8), systemd-journal-remote(8), systemd-journal-upload(8)

--chdir=

systemd-nspawn(1)

--children-max=

systemd-udevd.service(8), udevadm(8)

--chroot

systemd-detect-virt(1)

--class=

systemd-resolve(1)

--clean

systemd-tmpfiles(8)

--cleanup-db

udevadm(8)

--cname=

systemd-resolve(1)

--collect

systemd-mount(1), systemd-run(1)

--commit

systemd-machine-id-setup(1)

--compress

systemd-journal-remote(8)

--confirm-spawn

systemd(1)

--connections-max=

systemd-socket-proxyd(8)

--console

systemd-tty-ask-password-agent(1)

--container

systemd-detect-virt(1)

--cpu=

systemd-cgtop(1)

--crash-reboot

systemd(1)

--crash-shell

systemd(1)

--crash-vt=

systemd(1)

--create

systemd-tmpfiles(8)

--cursor=

journalctl(1), systemd-journal-upload(8)

--daemon

systemd-udevd.service(8)

--datagram

systemd-socket-activate(1)

--debug

systemd-udevd.service(8), udevadm(8)

--default-standard-error=

systemd(1)

--default-standard-output=

systemd(1)

--delay=

systemd-cgtop(1)

--depth=

systemd-cgtop(1)

--description=

systemd-mount(1), systemd-run(1)

--device-id-of-file=

udevadm(8)

--diff=

systemd-delta(1)

--directory=

coredumpctl(1), journalctl(1), systemd-journal-gatewayd.service(8), systemd-journal-upload(8), systemd-nspawn(1)

--discover

systemd-mount(1)

--disk-usage

journalctl(1)

--dmesg

journalctl(1)

--drop-capability=

systemd-nspawn(1)

--dry-run

systemctl(1), udevadm(8)

--dump-catalog

journalctl(1)

--dump-configuration-items

systemd(1)

--dump-core

systemd(1)

--echo

systemd-ask-password(1)

--ephemeral

systemd-nspawn(1)

--event-timeout=

systemd-udevd.service(8)

--exclude-prefix=

systemd-tmpfiles(8)

--exec-delay=

systemd-udevd.service(8)

--exit

udevadm(8)

--exit-if-exists=

udevadm(8)

--expect-reply=

busctl(1)

--export

udevadm(8)

--export-db

udevadm(8)

--export-prefix=

udevadm(8)

--fail

systemctl(1)

--failed

systemctl(1)

--fdname=

systemd-socket-activate(1)

--field=

coredumpctl(1), journalctl(1)

--fields

journalctl(1)

--file=

journalctl(1), systemd-journal-upload(8)

--firmware-setup

systemctl(1)

--flush

journalctl(1)

--flush-caches

systemd-resolve(1)

--follow

journalctl(1), systemd-journal-upload(8)

--force

halt(8), journalctl(1), machinectl(1), systemctl(1)

--format=

machinectl(1)

--from-pattern=

systemd-analyze(1)

--fsck=

systemd-mount(1)

--full

journalctl(1), loginctl(1), machinectl(1), systemctl(1), systemd-cgls(1)

--fuzz=

systemd-analyze(1)

--generators

systemd-analyze(1)

--getter=PROG [OPTIONS...]'

systemd-journal-remote(8)

--gid=

systemd-run(1)

--global

systemctl(1)

--gnutls-log=

systemd-journal-remote(8)

--grep=

journalctl(1)

--halt

halt(8), shutdown(8)

--header

journalctl(1)

--help

bootctl(1), busctl(1), coredumpctl(1), halt(8), hostnamectl(1), journalctl(1), localectl(1), loginctl(1), machinectl(1), networkctl(1), runlevel(8), shutdown(8), systemctl(1), systemd(1), systemd-analyze(1), systemd-ask-password(1), systemd-cat(1), systemd-cgls(1), systemd-cgtop(1), systemd-delta(1), systemd-detect-virt(1), systemd-escape(1), systemd-fsckd.service(8), systemd-hwdb(8), systemd-inhibit(1), systemd-journal-gatewayd.service(8), systemd-journal-remote(8), systemd-journal-upload(8), systemd-machine-id-setup(1), systemd-mount(1), systemd-notify(1), systemd-nspawn(1), systemd-path(1), systemd-resolve(1), systemd-run(1), systemd-socket-activate(1), systemd-socket-proxyd(8), systemd-suspend.service(8), systemd-sysctl.service(8), systemd-sysusers(8), systemd-tmpfiles(8), systemd-tty-ask-password-agent(1), systemd-udevd.service(8), telinit(8), timedatectl(1), udevadm(8)

--host=

busctl(1), hostnamectl(1), localectl(1), loginctl(1), machinectl(1), systemctl(1), systemd-analyze(1), systemd-mount(1), systemd-run(1), timedatectl(1)

--icon=

systemd-ask-password(1)

--id=

systemd-ask-password(1)

--identifier=

journalctl(1), systemd-cat(1)

--ignore-inhibitors

systemctl(1)

--ignore=

systemd-networkd-wait-online.service(8)

--image=

systemd-nspawn(1)

--inetd

systemd-socket-activate(1)

--interface=

systemd-networkd-wait-online.service(8), systemd-resolve(1)

--interval=

journalctl(1)

--iterations=

systemd-cgtop(1)

--job-mode=

systemctl(1)

--keep-unit

systemd-nspawn(1)

--kernel

udevadm(8)

--key=

systemd-journal-gatewayd.service(8), systemd-journal-remote(8), systemd-journal-upload(8)

--keyname=

systemd-ask-password(1)

--kill-signal=

systemd-nspawn(1)

--kill-who=

loginctl(1), machinectl(1), systemctl(1)

--legend=

systemd-resolve(1)

--level-prefix=

systemd-cat(1)

--lines=

journalctl(1), loginctl(1), machinectl(1), systemctl(1)

--link-journal=

systemd-nspawn(1)

--list

busctl(1), systemd-inhibit(1), systemd-mount(1), systemd-tty-ask-password-agent(1)

--list-boots

journalctl(1)

--list-catalog

journalctl(1)

--listen-http=

systemd-journal-remote(8)

--listen-https=

systemd-journal-remote(8)

--listen-raw=

systemd-journal-remote(8)

--listen=

systemd-socket-activate(1)

--log-color=

systemd(1)

--log-level=

systemd(1)

--log-location=

systemd(1)

--log-priority=

udevadm(8)

--log-target=

systemd(1)

--machine-id=

systemd(1)

--machine=

busctl(1), hostnamectl(1), journalctl(1), localectl(1), loginctl(1), machinectl(1), systemctl(1), systemd-analyze(1), systemd-cgls(1), systemd-cgtop(1), systemd-mount(1), systemd-nspawn(1), systemd-run(1), timedatectl(1)

--man=

systemd-analyze(1)

--mangle

systemd-escape(1)

--match=

busctl(1)

--max-addresses=

machinectl(1)

--merge

journalctl(1), systemd-journal-upload(8)

--message=

systemctl(1)

--mkdir

machinectl(1)

--mode=

systemd-inhibit(1)

--multiple

systemd-ask-password(1)

--name-match=

udevadm(8)

--name=

udevadm(8)

--network-bridge=

systemd-nspawn(1)

--network-interface=

systemd-nspawn(1)

--network-ipvlan=

systemd-nspawn(1)

--network-macvlan=

systemd-nspawn(1)

--network-namespace-path=

systemd-nspawn(1)

--network-veth

systemd-nspawn(1)

--network-veth-extra=

systemd-nspawn(1)

--network-zone=

systemd-nspawn(1)

--new-id128

journalctl(1)

--nice=

systemd-run(1)

--no-ask-password

hostnamectl(1), localectl(1), loginctl(1), machinectl(1), systemctl(1), systemd-mount(1), systemd-run(1), timedatectl(1)

--no-block

systemctl(1), systemd-mount(1), systemd-run(1)

--no-convert

localectl(1)

--no-full

journalctl(1)

--no-hostname

journalctl(1)

--no-legend

busctl(1), coredumpctl(1), loginctl(1), machinectl(1), networkctl(1), systemctl(1)

--no-output

systemd-ask-password(1)

--no-pager

busctl(1), coredumpctl(1), journalctl(1), localectl(1), loginctl(1), machinectl(1), networkctl(1), systemctl(1), systemd-analyze(1), systemd-cgls(1), systemd-delta(1), systemd-mount(1), systemd-resolve(1), timedatectl(1)

--no-reload

systemctl(1)

--no-sync

halt(8)

--no-tail

journalctl(1)

--no-tty

systemd-ask-password(1)

--no-variables

bootctl(1)

--no-wall

halt(8), shutdown(8), systemctl(1), telinit(8)

--no-wtmp

halt(8)

--notify-ready=

systemd-nspawn(1)

--now

systemctl(1)

--on-active=

systemd-run(1)

--on-boot=

systemd-run(1)

--on-calendar=

systemd-run(1)

--on-startup=

systemd-run(1)

--on-unit-active=

systemd-run(1)

--on-unit-inactive=

systemd-run(1)

--openpgp

systemd-resolve(1)

--options=

systemd-mount(1)

--order

systemd-analyze(1)

--order=

systemd-cgtop(1)

--output-fields=

journalctl(1)

--output=

coredumpctl(1), journalctl(1), loginctl(1), machinectl(1), systemctl(1), systemd-journal-remote(8)

--overlay-ro=

systemd-nspawn(1)

--overlay=

systemd-nspawn(1)

--owner=

systemd-mount(1)

--pager-end

journalctl(1)

--parent-match=

udevadm(8)

--path

systemd-escape(1)

--path-property=

systemd-run(1)

--path=

bootctl(1), udevadm(8)

--personality=

systemd-nspawn(1)

--pid=

systemd-notify(1)

--pipe

systemd-run(1)

--pivot-root=

systemd-nspawn(1)

--plain

systemctl(1)

--plymouth

systemd-tty-ask-password-agent(1)

--port=

systemd-nspawn(1)

--poweroff

halt(8), shutdown(8)

--prefix=

systemd-sysctl.service(8), systemd-tmpfiles(8)

--preset-mode=

systemctl(1)

--pretty

hostnamectl(1)

--print

systemd-machine-id-setup(1)

--print-path

bootctl(1)

--priority=

journalctl(1), systemd-cat(1)

--private-network

systemd-nspawn(1)

--private-users

systemd-detect-virt(1)

--private-users-chown

systemd-nspawn(1)

--private-users=

systemd-nspawn(1)

--property

udevadm(8)

--property-match=

udevadm(8)

--property=

loginctl(1), machinectl(1), systemctl(1), systemd-mount(1), systemd-nspawn(1), systemd-run(1), udevadm(8)

--protocol=

systemd-resolve(1)

--pty

systemd-run(1)

--query

systemd-tty-ask-password-agent(1)

--query=

udevadm(8)

--quiet

busctl(1), coredumpctl(1), journalctl(1), machinectl(1), systemctl(1), systemd-detect-virt(1), systemd-mount(1), systemd-nspawn(1), systemd-run(1)

--raw

systemd-cgtop(1), systemd-resolve(1)

--read-only

machinectl(1), systemd-nspawn(1)

--ready

systemd-notify(1)

--reboot

halt(8), shutdown(8)

--recursive

systemctl(1)

--recursive=

systemd-cgtop(1)

--register=

systemd-nspawn(1)

--reload

udevadm(8)

--remain-after-exit

systemd-run(1)

--remove

systemd-tmpfiles(8)

--require

systemd-analyze(1)

--reset-server-features

systemd-resolve(1)

--reset-statistics

systemd-resolve(1)

--resolve-names=

systemd-udevd.service(8), udevadm(8)

--reverse

coredumpctl(1), journalctl(1), systemctl(1)

--revert

systemd-resolve(1)

--root

udevadm(8)

--root-hash=

systemd-nspawn(1)

--root=

journalctl(1), systemctl(1), systemd-hwdb(8), systemd-machine-id-setup(1), systemd-sysusers(8), systemd-tmpfiles(8)

--rotate

journalctl(1)

--runtime

systemctl(1)

--save-state

systemd-journal-upload(8)

--scope

systemd-run(1)

--seal

systemd-journal-remote(8)

--search=

systemd-resolve(1)

--selinux-apifs-context=

systemd-nspawn(1)

--selinux-context=

systemd-nspawn(1)

--send-sighup

systemd-run(1)

--seqpacket

systemd-socket-activate(1)

--service

systemd-resolve(1)

--service-address=

systemd-resolve(1)

--service-txt=

systemd-resolve(1)

--service-type=

systemd-run(1)

--service-watchdogs=

systemd(1)

--set-dns=

systemd-resolve(1)

--set-dnssec=

systemd-resolve(1)

--set-domain=

systemd-resolve(1)

--set-llmnr=

systemd-resolve(1)

--set-mdns=

systemd-resolve(1)

--set-nta=

systemd-resolve(1)

--setenv=

machinectl(1), systemd-nspawn(1), systemd-run(1), systemd-socket-activate(1)

--settings=

systemd-nspawn(1)

--setup-keys

journalctl(1)

--show-cursor

journalctl(1)

--show-machine

busctl(1)

--show-status=

systemd(1)

--show-types

systemctl(1)

--signal=

loginctl(1), machinectl(1), systemctl(1)

--since

coredumpctl(1)

--since=

journalctl(1)

--size=

busctl(1)

--slice=

systemd-nspawn(1), systemd-run(1)

--socket-property=

systemd-run(1)

--split-mode

systemd-journal-remote(8)

--start-exec-queue

udevadm(8)

--state=

systemctl(1)

--static

hostnamectl(1)

--statistics

systemd-resolve(1)

--status

systemd-resolve(1)

--status=

systemd-notify(1)

--stop-exec-queue

udevadm(8)

--subsystem-match=

udevadm(8)

--subsystem-nomatch=

udevadm(8)

--suffix=

systemd-escape(1), systemd-path(1)

--sync

journalctl(1)

--sysname-match=

udevadm(8)

--system

busctl(1), journalctl(1), systemctl(1), systemd(1), systemd-analyze(1), systemd-journal-upload(8), systemd-mount(1), systemd-run(1)

--system-call-filter=

systemd-nspawn(1)

--tag-match=

udevadm(8)

--template=

systemd-escape(1), systemd-nspawn(1)

--test

systemd(1)

--timeout-idle-sec=

systemd-mount(1)

--timeout=

busctl(1), systemd-ask-password(1), systemd-networkd-wait-online.service(8), udevadm(8)

--timer-property=

systemd-run(1)

--tlsa

systemd-resolve(1)

--tmpfs=

systemd-nspawn(1)

--to-pattern=

systemd-analyze(1)

--transient

hostnamectl(1)

--trust=

systemd-journal-gatewayd.service(8), systemd-journal-remote(8), systemd-journal-upload(8)

--type=

systemctl(1), systemd-delta(1), systemd-mount(1), systemd-resolve(1), udevadm(8)

--udev

udevadm(8)

--uid=

machinectl(1), systemd-notify(1), systemd-run(1)

--umount

systemd-mount(1)

--unescape

systemd-escape(1)

--unique

busctl(1)

--unit

systemd-cgls(1)

--unit=

journalctl(1), systemd(1), systemd-run(1)

--until

coredumpctl(1)

--until=

journalctl(1)

--update-catalog

journalctl(1)

--url=

systemd-journal-remote(8), systemd-journal-upload(8)

--user

busctl(1), journalctl(1), systemctl(1), systemd(1), systemd-analyze(1), systemd-journal-upload(8), systemd-mount(1), systemd-run(1), systemd-tmpfiles(8)

--user-unit

systemd-cgls(1)

--user-unit=

journalctl(1)

--user=

systemd-nspawn(1)

--usr

systemd-hwdb(8)

--utc

journalctl(1)

--uuid=

systemd-nspawn(1)

--vacuum-files=

journalctl(1)

--vacuum-size=

journalctl(1)

--vacuum-time=

journalctl(1)

--value

loginctl(1), machinectl(1), systemctl(1)

--verbose

busctl(1), udevadm(8)

--verify

journalctl(1)

--verify-key=

journalctl(1)

--verify=

machinectl(1)

--version

bootctl(1), busctl(1), coredumpctl(1), hostnamectl(1), journalctl(1), localectl(1), loginctl(1), machinectl(1), networkctl(1), systemctl(1), systemd(1), systemd-analyze(1), systemd-cat(1), systemd-cgls(1), systemd-cgtop(1), systemd-delta(1), systemd-detect-virt(1), systemd-escape(1), systemd-fsckd.service(8), systemd-inhibit(1), systemd-journal-gatewayd.service(8), systemd-journal-remote(8), systemd-journal-upload(8), systemd-machine-id-setup(1), systemd-mount(1), systemd-notify(1), systemd-nspawn(1), systemd-path(1), systemd-resolve(1), systemd-run(1), systemd-socket-activate(1), systemd-socket-proxyd(8), systemd-suspend.service(8), systemd-sysctl.service(8), systemd-sysusers(8), systemd-tmpfiles(8), systemd-tty-ask-password-agent(1), systemd-udevd.service(8), timedatectl(1), udevadm(8)

--vm

systemd-detect-virt(1)

--volatile

systemd-nspawn(1)

--volatile=

systemd-nspawn(1)

--wait

systemctl(1), systemd-run(1)

--wall

systemd-tty-ask-password-agent(1)

--watch

systemd-tty-ask-password-agent(1)

--watch-bind=

busctl(1)

--what=

systemd-inhibit(1)

--who=

systemd-inhibit(1)

--why=

systemd-inhibit(1)

--wtmp-only

halt(8)
<