systemd(1)

NAME#

systemd, init - systemd system and service manager

SYNOPSIS#

/usr/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. Separate instances are started for logged-in users to start their services.

systemd is usually not invoked directly by the user, but is installed as the /sbin/init symlink and started during early boot. The user manager instances are started automatically through the [email protected](5) service.

For compatibility with SysV, if the binary is called as init and is not the first process on the machine (PID 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.

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/, /proc/, and /dev/.

systemd will also reset the system clock during early boot if it appears to be set incorrectly. See "System clock epoch" section below.

Note that some but not all interfaces provided by systemd are covered by the Interface Portability and Stability Promise[1].

The D-Bus API of systemd is described in org.freedesktop.systemd1(5) and org.freedesktop.LogControl1(5).

Systems which invoke systemd in a container or initrd environment should implement the Container Interface[2] or initrd Interface[3] specifications, respectively.

UNITS#

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 files, dynamically from system state or programmatically at runtime. Units may be in a number of states, described in the following table. Note that the various unit types may have a number of additional substates, which are mapped to the generalized unit states described here.

Table 1. Unit ACTIVE states

The following unit types are available:

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.

On first boot, systemd will enable or disable units according to preset policy. See systemd.preset(5) and "First Boot Semantics" in machine-id(5).

systemd only keeps a minimal set of units loaded into memory. Specifically, the only units that are kept loaded into memory are those for which at least one of the following conditions is true:

systemd will automatically and implicitly load units from disk — if they are not loaded yet — as soon as operations are requested for them. Thus, in many respects, the fact whether a unit is loaded or not is invisible to clients. Use systemctl list-units --all to comprehensively list all units currently loaded. Any unit for which none of the conditions above applies is promptly unloaded. Note that when a unit is unloaded from memory its accounting data is flushed out too. However, this data is generally not lost, as a journal log record is generated declaring the consumed resources whenever a unit shuts down.

Processes systemd spawns are placed in individual Linux control groups named after the unit which they belong to in the private systemd hierarchy. (see Control Groups v2[4] 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/), 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.

Note that transactions are generated independently of a unit's state at runtime, hence, for example, if a start job is requested on an already started unit, it will still generate a transaction and wake up any inactive dependencies (and cause propagation of other jobs as per the defined relationships). This is because the enqueued job is at the time of execution compared to the target unit's state and is marked successful and complete when both satisfy. However, this job also pulls in other dependencies due to the defined relationships and thus leads to, in our example, start jobs for any of those inactive units getting queued as well.

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).

DIRECTORIES#

System unit directories

User unit directories

SysV init scripts directory

SysV runlevel link farm directory

SIGNALS#

The service listens to various UNIX process signals that can be used to request various actions asynchronously. The signal handling is enabled very early during boot, before any further processes are invoked. However, a supervising container manager or similar that intends to request these operations via this mechanism must take into consideration that this functionality is not available during the earliest initialization phase. An sd_notify() notification message carrying the X_SYSTEMD_SIGNALS_LEVEL=2 field is emitted once the signal handlers are enabled, see below. This may be used to schedule submission of these signals correctly.

SIGTERM

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-irreversibly.

SIGINT

systemd user managers treat this signal the same way as SIGTERM.

SIGWINCH

This signal is ignored by systemd user managers.

SIGPWR

SIGUSR1

SIGUSR2

SIGHUP

SIGRTMIN+0

SIGRTMIN+1

SIGRTMIN+2

SIGRTMIN+3

SIGRTMIN+4

SIGRTMIN+5

SIGRTMIN+6

SIGRTMIN+7

Added in version 254.

SIGRTMIN+13

SIGRTMIN+14

SIGRTMIN+15

SIGRTMIN+16

SIGRTMIN+17

Added in version 254.

SIGRTMIN+20

You may want to use SetShowStatus() instead of SIGRTMIN+20 in order to prevent race conditions. See org.freedesktop.systemd1(5).

SIGRTMIN+21

You may want to use SetShowStatus() instead of SIGRTMIN+21 in order to prevent race conditions. See org.freedesktop.systemd1(5).

SIGRTMIN+22

SIGRTMIN+23

Added in version 239.

SIGRTMIN+24

Added in version 195.

SIGRTMIN+25

The systemd system manager treats this signal the same way as SIGTERM.

Added in version 250.

SIGRTMIN+26

Added in version 239.

SIGRTMIN+27, SIGRTMIN+28

Added in version 239.

ENVIRONMENT#

The environment block for the system manager is initially set by the kernel. (In particular, "key=value" assignments on the kernel command line are turned into environment variables for PID 1). For the user manager, the system manager sets the environment as described in the "Environment Variables in Spawned Processes" section of systemd.exec(5). The DefaultEnvironment= setting in the system manager applies to all services including [email protected]. Additional entries may be configured (as for any other service) through the Environment= and EnvironmentFile= settings for [email protected] (see systemd.exec(5)). Also, additional environment variables may be set through the ManagerEnvironment= setting in systemd-system.conf(5) and systemd-user.conf(5).

Some of the variables understood by systemd:

$SYSTEMD_LOG_LEVEL

This can be overridden with --log-level=.

$SYSTEMD_LOG_COLOR

This can be overridden with --log-color=.

$SYSTEMD_LOG_TIME

This can be overridden with --log-time=.

Added in version 246.

$SYSTEMD_LOG_LOCATION

This can be overridden with --log-location=.

$SYSTEMD_LOG_TID

Added in version 247.

$SYSTEMD_LOG_TARGET

This can be overridden with --log-target=.

$SYSTEMD_LOG_RATELIMIT_KMSG

Added in version 254.

$XDG_CONFIG_HOME, $XDG_CONFIG_DIRS, $XDG_DATA_HOME, $XDG_DATA_DIRS

$SYSTEMD_UNIT_PATH, $SYSTEMD_GENERATOR_PATH, $SYSTEMD_ENVIRONMENT_GENERATOR_PATH

These variables may contain a list of paths, separated by colons (":"). When set, if the list ends with an empty component ("...:"), this list is prepended to the usual set of paths. Otherwise, the specified list replaces the usual set of paths.

$SYSTEMD_PAGER, $PAGER

Note: if $SYSTEMD_PAGERSECURE is not set, $SYSTEMD_PAGER and $PAGER can only be used to disable the pager (with "cat" or ""), and are otherwise ignored.

$SYSTEMD_LESS

Users might want to change two options in particular:

K

If the value of $SYSTEMD_LESS does not include "K", and the pager that is invoked is less, Ctrl+C will be ignored by the executable, and needs to be handled by the pager.

X

Note that setting the regular $LESS environment variable has no effect for less invocations by systemd tools.

See less(1) for more discussion.

$SYSTEMD_LESSCHARSET

Note that setting the regular $LESSCHARSET environment variable has no effect for less invocations by systemd tools.

$SYSTEMD_PAGERSECURE

This option takes a boolean argument. When set to true, the "secure mode" of the pager is enabled. In "secure mode", LESSSECURE=1 will be set when invoking the pager, which instructs the pager to disable commands that open or create new files or start new subprocesses. Currently only less(1) is known to understand this variable and implement "secure mode".

When set to false, no limitation is placed on the pager. Setting SYSTEMD_PAGERSECURE=0 or not removing it from the inherited environment may allow the user to invoke arbitrary commands.

When $SYSTEMD_PAGERSECURE is not set, systemd tools attempt to automatically figure out if "secure mode" should be enabled and whether the pager supports it. "Secure mode" is enabled if the effective UID is not the same as the owner of the login session, see geteuid(2) and sd_pid_get_owner_uid(3), or when running under sudo(8) or similar tools ($SUDO_UID is set [6]). In those cases, SYSTEMD_PAGERSECURE=1 will be set and pagers which are not known to implement "secure mode" will not be used at all. Note that this autodetection only covers the most common mechanisms to elevate privileges and is intended as convenience. It is recommended to explicitly set $SYSTEMD_PAGERSECURE or disable the pager.

Note that if the $SYSTEMD_PAGER or $PAGER variables are to be honoured, other than to disable the pager, $SYSTEMD_PAGERSECURE must be set too.

$SYSTEMD_COLORS

$SYSTEMD_URLIFY

$LISTEN_PID, $LISTEN_FDS, $LISTEN_FDNAMES

$NOTIFY_SOCKET

For further environment variables understood by systemd and its various components, see Known Environment Variables[7].

KERNEL COMMAND LINE#

When run as the system instance, systemd parses a number of options listed below. They can be specified as kernel command line arguments which are parsed from a number of sources depending on the environment in which systemd is executed. If run inside a Linux container, these options are parsed from the command line arguments passed 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 and from the "SystemdOptions" EFI variable (on EFI systems) instead. Options from /proc/cmdline have higher priority.

Note: use of "SystemdOptions" is deprecated.

The following variables are understood:

systemd.unit=, rd.systemd.unit=

systemd.dump_core

Added in version 233.

systemd.crash_chvt

Added in version 233.

systemd.crash_shell

Added in version 233.

systemd.crash_action=

Added in version 256.

systemd.confirm_spawn

Added in version 233.

systemd.service_watchdogs=

Added in version 237.

systemd.show_status

Added in version 233.

systemd.status_unit_format=

Added in version 243.

systemd.log_color, systemd.log_level=, systemd.log_location, systemd.log_target=, systemd.log_time, systemd.log_tid, systemd.log_ratelimit_kmsg

systemd.default_standard_output=, systemd.default_standard_error=

systemd.setenv=

systemd.machine_id=

Added in version 229.

systemd.set_credential=, systemd.set_credential_binary=

For further information see System and Service Credentials[8] documentation.

Added in version 251.

systemd.import_credentials=

Added in version 251.

quiet

Added in version 186.

debug

Added in version 205.

emergency, rd.emergency, -b

Added in version 186.

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

Added in version 186.

2, 3, 4, 5

Added in version 186.

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=

Added in version 186.

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

SYSTEM CREDENTIALS#

During initialization the service manager will import credentials from various sources into the system's set of credentials, which can then be propagated into services and consumed by generators:

Invoke systemd-creds(1) as follows to see the list of credentials passed into the system:

# systemd-creds --system list

For further information see System and Service Credentials[8] documentation.

The service manager when run as PID 1 consumes the following system credentials:

vmm.notify_socket

This feature is useful for machine managers or other processes on the host to receive a notification via VSOCK when a virtual machine has finished booting.

Added in version 254.

system.machine_id

Added in version 254.

For a list of system credentials various other components of systemd consume, see systemd.system-credentials(7).

READINESS PROTOCOL#

The service manager implements a readiness notification protocol both between the manager and its services (i.e. down the stack), and between the manager and a potential supervisor further up the stack (the latter could be a machine or container manager, or in case of a per-user service manager the system service manager instance). The basic protocol (and the suggested API for it) is described in sd_notify(3).

The notification socket the service manager (including PID 1) uses for reporting readiness to its own supervisor is set via the usual $NOTIFY_SOCKET environment variable (see above). Since this is directly settable only for container managers and for the per-user instance of the service manager, an additional mechanism to configure this is available, in particular intended for use in VM environments: the vmm.notify_socket system credential (see above) may be set to a suitable socket (typically an AF_VSOCK one) via SMBIOS Type 11 vendor strings. For details see above.

The notification protocol from the service manager up the stack towards a supervisor supports a number of extension fields that allow a supervisor to learn about specific properties of the system and track its boot progress. Specifically the following fields are sent:

Added in version 256.

Added in version 256.

Signals sent to PID 1 before this message is sent might not be handled correctly yet. A consumer of these messages should parse the value as an unsigned integer that indicates the level of support. For now only the mentioned level 2 is defined, but later on additional levels might be defined with higher integers, that will implement a superset of the currently defined behaviour.

Added in version 256.

Added in version 256.

Added in version 256.

Added in version 256.

Note that these extension fields are sent in addition to the regular "READY=1" and "RELOADING=1" notifications.

OPTIONS#

systemd is only very rarely invoked directly, since it is started early and is already running by the time users may interact with it. Normally, tools like systemctl(1) are used to give commands to the manager. Since systemd is usually not invoked directly, the options listed below are mostly useful for debugging and special purposes.

Introspection and debugging options#

Those options are used for testing and introspection, and systemd may be invoked with them at any time:

--dump-configuration-items

--dump-bus-properties

Added in version 239.

--test

--system, --user

-h, --help

--version

Options that duplicate kernel command line settings#

Those options correspond directly to options listed above in "Kernel Command Line". Both forms may be used equivalently for the system manager, but it is recommended to use the forms listed above in this context, because they are properly namespaced. When an option is specified both on the kernel command line and as a normal command line argument, the latter has higher precedence.

When systemd is used as a user manager, the kernel command line is ignored and only the options described below are understood. Nevertheless, systemd is usually started in this mode through the [email protected](5) service, which is shared between all users. It may be more convenient to use configuration files to modify settings (see systemd-user.conf(5)), or environment variables. See the "Environment" section above for a discussion of how the environment block is set.

--unit=

--dump-core

--crash-vt=VT

Added in version 227.

--crash-shell

--crash-action=

Added in version 256.

--confirm-spawn

--show-status

Added in version 244.

--log-color

Added in version 244.

--log-level=

--log-location

Added in version 244.

--log-target=

--log-time=

Added in version 246.

--machine-id=

Added in version 229.

--service-watchdogs

Added in version 237.

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

SYSTEM CLOCK EPOCH#

When systemd is started or restarted, it may set the system clock to the "epoch". This mechanism is used to ensure that the system clock remains somewhat reasonably initialized and roughly monotonic across reboots, in case no battery-backed local RTC is available or it does not work correctly.

The epoch is the lowest date above which the system clock time is assumed to be set correctly. When initializing, the local clock is advanced to the epoch if it was set to a lower value. As a special case, if the local clock is sufficiently far in the future (by default 15 years, but this can be configured at build time), the hardware clock is assumed to be broken, and the system clock is rewound to the epoch.

The epoch is set to the highest of: the build time of systemd, the modification time ("mtime") of /usr/lib/clock-epoch, and the modification time of /var/lib/systemd/timesync/clock.

FILES#

/run/systemd/notify

/run/systemd/private

/dev/initctl

/usr/lib/clock-epoch

Added in version 247.

/var/lib/systemd/timesync/clock

Added in version 257.

HISTORY#

systemd 252

Added in version 252.

SEE ALSO#

The systemd Homepage[9], systemd-system.conf(5), locale.conf(5), systemctl(1), journalctl(1), systemd-notify(1), daemon(7), sd-daemon(3), org.freedesktop.systemd1(5), systemd.unit(5), systemd.special(7), pkg-config(1), kernel-command-line(7), bootup(7), systemd.directives(7), org.freedesktop.systemd1(5)

For more information about the concepts and ideas behind systemd, please refer to the Original Design Document[10].

NOTES#

1.

Interface Portability and Stability Promise

2.

Container Interface

3.

initrd Interface

4.

Control Groups v2

5.

XDG Base Directory specification

6.

It is recommended for other tools to set and check $SUDO_UID as appropriate, treating it is a common interface.

7.

Known Environment Variables

8.

System and Service Credentials

9.

systemd Homepage

10.

Original Design Document