systemd.journal-fields

title: systemd.journal-fields(7)

summary: Special journal fields

text:
# systemd.journal-fields(7)

## NAME
systemd.journal-fields - Special journal fields

## DESCRIPTION
Entries in the journal (as written by systemd-journald.service(8)) resemble a UNIX process environment block in syntax but with fields that may include binary data. Primarily, fields are formatted UTF-8 text strings, and binary encoding 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 meanings. 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 systemd-id128 new.

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.

INVOCATION_ID=, USER_INVOCATION_ID=

A randomized, unique 128-bit ID identifying each runtime cycle of the unit. This is different from _SYSTEMD_INVOCATION_ID in that it is only used for messages coming from systemd code (e.g. logs from the system/user manager or from forked processes performing systemd-related setup).

SYSLOG_FACILITY=, SYSLOG_IDENTIFIER=, SYSLOG_PID=, SYSLOG_TIMESTAMP=

Syslog compatibility fields containing the facility (formatted as decimal string), the identifier string (i.e. "tag"), the client PID, and the timestamp as specified in the original datagram. (Note that the tag is usually derived from glibc's program_invocation_short_name variable, see program_invocation_short_name(3).) Note that the journal service does not validate the values of any structured journal fields whose name is not prefixed with an underscore, and this includes any syslog related fields such as these. Hence, applications that supply a facility, PID, or log level are expected to do so properly formatted, i.e. as numeric integers formatted as decimal strings.

SYSLOG_RAW=

The original contents of the syslog line as received in the syslog datagram. This field is only included if the MESSAGE= field was modified compared to the original payload or the timestamp could not be located properly and is not included in SYSLOG_TIMESTAMP=. Message truncation occurs when when the message contains leading or trailing whitespace (trailing and leading whitespace is stripped), or it contains an embedded NUL byte (the NUL byte and anything after it is not included). Thus, the original syslog line is either stored as SYSLOG_RAW= or it can be recreated based on the stored priority and facility, timestamp, identifier, and the message payload in MESSAGE=.

DOCUMENTATION=

A documentation URL with further information about the topic of the log message. Tools such as journalctl will include a hyperlink to an URL specified this way in their output. Should be an "http://", "https://", "file:/", "man:" or "info:" URL.

TID=

The numeric thread ID (TID) the log message originates from.

UNIT=, USER_UNIT=

The name of a unit. Used by the system and user managers when logging about specific units. When --unit=name or --user-unit=name are used with journalctl(1), a match pattern that includes "UNIT=name.service" or "USER_UNIT=name.service" will be generated.

## 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_USER_SLICE=, _SYSTEMD_SESSION=, _SYSTEMD_OWNER_UID=

The control group path in the systemd hierarchy, 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)), eof (if this was the last log record of a stream and the stream ended without a final newline character), or pid-change (if the process which generated the log output changed in the middle of a line). Note that this record is not generated when a normal newline character was used for marking the log line end.

_NAMESPACE=

If this file was written by a systemd-journald instance managing a journal namespace that is not the default, this field contains the namespace identifier. See systemd-journald.service(8) for details about journal namespaces.

## 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, contains the major and minor numbers of the device node, separated by ":" and prefixed by "b". Similarly 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 Journal Export Format[1] or the Journal JSON Format[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), systemd-journald.service(8), journalctl(1), journald.conf(5), sd-journal(3), coredumpctl(1), systemd.directives(7)

## NOTES
1.

Journal Export Format

https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format

2.

Journal JSON Format

https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format


systemd.net-naming-scheme

package: systemd

title: systemd.net-naming-scheme(7)

summary: Network device naming schemes

text:
# systemd.net-naming-scheme(7)

## NAME
systemd.net-naming-scheme - Network device naming schemes

## DESCRIPTION
Network interfaces names and MAC addresses may be generated based on certain stable interface attributes. This is possible when there is enough information about the device to generate those attributes and the use of this information is configured. This page describes interface naming, i.e. what possible names may be generated. Those names are generated by the systemd-udevd.service(8) builtin net_id and exported as udev properties (ID_NET_NAME_ONBOARD=, ID_NET_LABEL_ONBOARD=, ID_NET_NAME_PATH=, ID_NET_NAME_SLOT=).

Names and MAC addresses are derived from various stable device metadata attributes. Newer versions of udev take more of these attributes into account, improving (and thus possibly changing) the names and addresses used for the same devices. Different versions of those generation rules are called "naming schemes". The default naming scheme is chosen at compilation time. Usually this will be the latest implemented version, but it is also possible to set one of the older versions to preserve compatibility. This may be useful for example for distributions, which may introduce new versions of systemd in stable releases without changing the naming scheme. The naming scheme may also be overridden using the net.naming-scheme= kernel command line switch, see systemd-udevd.service(8). Available naming schemes are described below.

After the udev properties have been generated, appropriate udev rules may be used to actually rename devices based on those properties. See the description of NamePolicy= and MACAddressPolicy= in systemd.link(5).

Note that while the concept of network interface naming schemes is primarily relevant in the context of systemd-udevd.service, the systemd-nspawn(1) container manager also takes it into account when naming network interfaces, see below.

## NAMING
All names start with a two-character prefix that signifies the interface type.

Table 1. Two character prefixes based on the type of interface

Prefix

Description

en

Ethernet

ib

InfiniBand

sl

Serial line IP (slip)

wl

Wireless local area network (WLAN)

ww

Wireless wide area network (WWAN)

The udev

net_id builtin exports the following udev device properties:

ID_NET_NAME_ONBOARD=prefixonumber

This name is set based on the numeric ordering information given by the firmware for on-board devices. The name consists of the prefix, letter o, and a number specified by the firmware. This is only available for PCI devices.

ID_NET_LABEL_ONBOARD=prefix label

This property is set based on textual label given by the firmware for on-board devices. The name consists of the prefix concatenated with the label. This is only available for PCI devices.

ID_NET_NAME_MAC=prefixxAABBCCDDEEFF

This name consists of the prefix, letter x, and 12 hexadecimal digits of the MAC address. It is available if the device has a fixed MAC address. Because this name is based on an attribute of the card itself, it remains "stable" when the device is moved (even between machines), but will change when the hardware is replaced.

ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port], ID_NET_NAME_SLOT=prefixvslot, ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port]bnumber, ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port]uport...[cconfig][iinterface], ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port]vslot

This property describes the slot position. Different schemes are used depending on the bus type, as described in the table below. In case of USB, BCMA, and SR-VIO devices, the full name consists of the prefix, PCI slot identifier, and USB or BCMA or SR-VIO slot identifier. The first two parts are denoted as "..." in the table below. Table 2. Slot naming schemes

Format

Description

prefix [Pdomain] sslot [ffunction] [nport_name | ddev_port]

PCI slot number

prefix vslot

VIO slot number (IBM PowerVM)

... bnumber

Broadcom bus (BCMA) core number

... uport... [cconfig] [iinterface]

USB port number chain

... vslot

SR-VIO slot number

The PCI domain is only prepended when it is not 0. All multi-function PCI devices will carry the

ffunction number in the device name, including the function 0 device. For non-multi-function devices, the number is suppressed if 0. The port name port_name is used, or the port number ddev_port if the name is not known.

For BCMA devices, the core number is suppressed when 0.

For USB devices the full chain of port numbers of hubs is composed. If the name gets longer than the maximum number of 15 characters, the name is not exported. The usual USB configuration number 1 and interface number 0 values are suppressed.

SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of v and the virtual device number, with any leading zeros removed. The bus number is ignored.

In some configurations a parent PCI bridge of a given network controller may be associated with a slot. In such case we don't generate this device property to avoid possible naming conflicts.

ID_NET_NAME_PATH=prefixcbus_id, ID_NET_NAME_PATH=prefixavendormodeliinstance, ID_NET_NAME_PATH=prefixiaddressnport_name, ID_NET_NAME_PATH=prefix[Pdomain]pbussslot[ffunction][nphys_port_name|ddev_port], ID_NET_NAME_PATH=prefix[Pdomain]pbussslot[ffunction][nphys_port_name|ddev_port]bnumber, ID_NET_NAME_PATH=prefix[Pdomain]pbussslot[ffunction][nphys_port_name|ddev_port]uport...[cconfig][iinterface]

This property describes the device installation location. Different schemes are used depending on the bus type, as described in the table below. For BCMA and USB devices, PCI path information must known, and the full name consists of the prefix, PCI slot identifier, and USB or BCMA location. The first two parts are denoted as "..." in the table below. Table 3. Path naming schemes

Format

Description

prefix cbus_id

CCW or grouped CCW device identifier

prefix avendor model iinstance

ACPI path names for ARM64 platform devices

prefix iaddress nport_name

Netdevsim (simulated networking device) device number and port name

prefix [Pdomain] pbus sslot [ffunction] [nphys_port_name | ddev_port]

PCI geographical location

... bnumber

Broadcom bus (BCMA) core number

... uport... [cconfig] [iinterface]

USB port number chain

CCW and grouped CCW devices are found in IBM System Z mainframes. Any leading zeros and dots are suppressed.

For PCI, BCMA, and USB devices, the same rules as described above for slot naming are used.

## HISTORY
The following "naming schemes" have been defined (which may be chosen at system boot-up time via the net.naming-scheme= kernel command line switch, see above):

v238

This is the naming scheme that was implemented in systemd 238.

v239

Naming was changed for virtual network interfaces created with SR-IOV and NPAR and for devices where the PCI network controller device does not have a slot number associated. SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of "vport", where port is the virtual device number. Previously those virtual devices were named as if completely independent.

The ninth and later NPAR virtual devices are named following the scheme used for the first eight NPAR partitions. Previously those devices were not renamed and the kernel default ("ethN") was used.

Names are also generated for PCI devices where the PCI network controller device does not have an associated slot number itself, but one of its parents does. Previously those devices were not renamed and the kernel default was used.

v240

The "ib" prefix and stable names for infiniband devices are introduced. Previously those devices were not renamed. The ACPI index field (used in ID_NET_NAME_ONBOARD=) is now also used when 0.

A new naming policy NamePolicy=keep was introduced. With this policy, if the network device name was already set by userspace, the device will not be renamed again. Previously, this naming policy applied implicitly, and now it must be explicitly requested. Effectively, this means that network devices will be renamed according to the configuration, even if they have been renamed already, if keep is not specified as the naming policy in the .link file. See systemd.link(5) for a description of NamePolicy=.

v241

MACAddressPolicy=persistent was extended to set MAC addresses based on the device name. Previously addresses were only based on the ID_NET_NAME_* attributes, which meant that interface names would never be generated for virtual devices. Now a persistent address will be generated for most devices, including in particular bridges. Note: when userspace does not set a MAC address for a bridge device, the kernel will initially assign a random address, and then change it when the first device is enslaved to the bridge. With this naming policy change, bridges get a persistent MAC address based on the bridge name instead of the first enslaved device.

v243

Support for renaming netdevsim (simulated networking) devices was added. Previously those devices were not renamed. Previously two-letter interface type prefix was prepended to ID_NET_LABEL_ONBOARD=. This is not done anymore.

v245

When systemd-nspawn(1) derives the name for the host side of the network interface created with --network-veth from the container name it previously simply truncated the result at 15 characters if longer (since that's the maximum length for network interface names). From now on, for any interface name that would be longer than 15 characters the last 4 characters are set to a 24bit hash value of the full interface name. This way network interface name collisions between multiple similarly named containers (who only differ in container name suffix) should be less likely (but still possible, since the 24bit hash value is very small).

v247

When a PCI slot is associated with a PCI bridge that has multiple child network controllers, the same value of the ID_NET_NAME_SLOT property might be derived for those controllers. This would cause a naming conflict if the property is selected as the device name. Now, we detect this situation and don't produce the ID_NET_NAME_SLOT property.

v249

PCI hotplug slot names for the s390 PCI driver are a hexadecimal representation of the function_id device attribute. This attribute is now used to build the ID_NET_NAME_SLOT. Before that, all slot names were parsed as decimal numbers, which could either result in an incorrect value of the ID_NET_NAME_SLOT property or none at all. Some firmware and hypervisor implementations report unreasonable high numbers for the onboard index. To prevent the generation of bogus onbard interface names, index numbers greater than 16381 (2^14-1) were ignored. For s390 PCI devices index values up to 65535 (2^16-1) are valid. To account for that, the limit is increased to now 65535.

The udev rule NAME= replaces ":", "/", and "%" with an underscore ("_"), and refuses strings which contain only numerics.

Note that latest may be used to denote the latest scheme known (to this particular version of systemd).

## EXAMPLES
Example 1. Using udevadm test-builtin to display device properties

```
$ udevadm test-builtin net_id /sys/class/net/enp0s31f6
...
Using default interface naming scheme 'v243'.
ID_NET_NAMING_SCHEME=v243
ID_NET_NAME_MAC=enx54ee75cb1dc0
ID_OUI_FROM_DATABASE=Wistron InfoComm(Kunshan)Co.,Ltd.
ID_NET_NAME_PATH=enp0s31f6
...
```

Example 2. PCI Ethernet card with firmware index "1"

```
ID_NET_NAME_ONBOARD=eno1
ID_NET_NAME_ONBOARD_LABEL=Ethernet Port 1

```

Example 3. PCI Ethernet card in hotplug slot with firmware index number

```
# /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1
ID_NET_NAME_MAC=enx000000000466
ID_NET_NAME_PATH=enp5s0
ID_NET_NAME_SLOT=ens1
```

Example 4. PCI Ethernet multi-function card with 2 ports

```
# /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.0/net/enp2s0f0
ID_NET_NAME_MAC=enx78e7d1ea46da
ID_NET_NAME_PATH=enp2s0f0
# /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1
ID_NET_NAME_MAC=enx78e7d1ea46dc
ID_NET_NAME_PATH=enp2s0f1
```

Example 5. PCI WLAN card

```
# /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0
ID_NET_NAME_MAC=wlx0024d7e31130
ID_NET_NAME_PATH=wlp3s0
```

Example 6. PCI IB host adapter with 2 ports

```
# /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0
ID_NET_NAME_PATH=ibp21s0f0
# /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1
ID_NET_NAME_PATH=ibp21s0f1
```

Example 7. USB built-in 3G modem

```
# /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.4/2-1.4:1.6/net/wwp0s29u1u4i6
ID_NET_NAME_MAC=wwx028037ec0200
ID_NET_NAME_PATH=wwp0s29u1u4i6
```

Example 8. USB Android phone

```
# /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2:1.0/net/enp0s29u1u2
ID_NET_NAME_MAC=enxd626b3450fb5
ID_NET_NAME_PATH=enp0s29u1u2
```

Example 9. s390 grouped CCW interface

```
# /sys/devices/css0/0.0.0007/0.0.f5f0/group_device/net/encf5f0
ID_NET_NAME_MAC=enx026d3c00000a
ID_NET_NAME_PATH=encf5f0
```

## SEE ALSO
udev(7), udevadm(8), Predictable Network Interface Names[1], systemd-nspawn(1)

## NOTES
1.

Predictable Network Interface Names

https://systemd.io/PREDICTABLE_INTERFACE_NAMES


systemd.offline-updates

title: systemd.offline-updates(7)

text:
# systemd.offline-updates(7)

## 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 GNOME design whiteboard[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 update scripts should exit only after the update is finished. It is expected that the service which performs the update 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/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 org.freedesktop.login1(5) for details about the logind D-Bus API.

4.The update service should declare DefaultDependencies=no, Requires=sysinit.target, After=sysinit.target, After=system-update-pre.target, Before=system-update.target and explicitly pull in any other services it requires.

5.It may be desirable to always run an auxiliary unit when booting into offline-updates mode, which itself does not install updates. To do this create a .service file with Wants=system-update-pre.target and Before=system-update-pre.target and add a symlink to that file under /lib/systemd/system/system-update.target.wants .

## 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


systemd.special

title: systemd.special(7)

summary: Special systemd units

text:
# systemd.special(7)

## NAME
systemd.special - Special systemd units

## SYNOPSIS
basic.target, bluetooth.target, cryptsetup-pre.target, cryptsetup.target, veritysetup-pre.target, veritysetup.target, ctrl-alt-del.target, blockdev@.target, boot-complete.target, default.target, emergency.target, exit.target, final.target, first-boot-complete.target, getty.target, getty-pre.target, graphical.target, halt.target, hibernate.target, hybrid-sleep.target, suspend-then-hibernate.target, initrd.target, initrd-fs.target, initrd-root-device.target, initrd-root-fs.target, initrd-usr-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-veritysetup.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, system-update-pre.target, time-set.target, time-sync.target, timers.target, umount.target, usb-gadget.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.

## UNITS MANAGED BY THE SYSTEM SERVICE MANAGER

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

boot-complete.target

This target is intended as generic synchronization point for services that shall determine or act on whether the boot process completed successfully. Order units that are required to succeed for a boot process to be considered successful before this unit, and add a Requires= dependency from the target unit to them. Order units that shall only run when the boot process is considered successful after the target unit and pull in the target from it, also with Requires=. Note that by default this target unit is not part of the initial boot transaction, but is supposed to be pulled in only if required by units that want to run only on successful boots. See systemd-boot-check-no-failures.service(8) for a service that implements a generic system health check and orders itself before boot-complete.target.

See systemd-bless-boot.service(8) for a service that propagates boot success information to the boot loader, and orders itself after boot-complete.target.

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.

veritysetup.target

A target that pulls in setup services for all verity integrity protected 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. See bootup(7) for more discussion. The default unit systemd starts at bootup can be overridden with the systemd.unit= kernel command line option, or more conveniently, with the short names like single, rescue, 1, 3, 5, ...; see systemd(1).

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 other 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 may be used by specifying emergency on the kernel command line; 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. 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.

Note that depending on how emergency.target is reached, the root file system might be mounted read-only or read-write (no remounting is done specially for this target). For example, the system may boot with root mounted read-only when ro is used on the kernel command line and remain this way for emergency.target, or the system may transition to emergency.target after the system has been partially booted and disks have already been remounted read-write.

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

This is the default target in the initramfs, similar to default.target in the main system. It is used to mount the real root and transition to it. See bootup(7) for more discussion.

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 the x-initrd.mount mount option set and do not have the noauto mount option set. It is also indirectly ordered after sysroot.mount. Thus, once this target is reached the /sysroot/ hierarchy is fully set up, in preparation for the transition to the host OS.

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's root= setting (or equivalent).

initrd-usr-fs.target

systemd-fstab-generator(3) automatically adds dependencies of type Before= to the sysusr-usr.mount unit, which is generated from the kernel command line's usr= switch. Services may order themselves after this target unit in order to run once the /sysusr/ hierarchy becomes available, on systems that come up initially without a root file system, but with an initialized /usr/ and need to access that before setting up the root file system to ultimately switch to. On systems where usr= is not used this target is ordered after sysroot.mount and thus mostly equivalent to initrd-root-fs.target. In effect on any system once this target is reached the file system backing /usr/ is mounted, though possibly at two different locations, either below the /sysusr/ or the /sysroot/ hierarchies.

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 Running Services After the Network is up[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 (as opposed to consume functionality of other hosts) generally do not need to pull this in.

systemd automatically adds dependencies of type Wants= and After= for this target unit to all SysV init script service units with an LSB header referring to the "$network" facility.

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 power off 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-veritysetup.target

Similar to veritysetup.target, but for verity integrity protected devices which are accessed over the network. It is used for veritytab(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 always be active after boot. By default the generic system.slice slice unit as well as the root slice unit -.slice are pulled in and ordered before this unit (see below). Adding slice units to slices.target is generally not necessary. Instead, when some unit that uses Slice= is started, the specified slice will be started automatically. Adding WantedBy=slices.target lines to the [Install] section should only be done for units that need to be always active. In that case care needs to be taken to avoid creating a loop through the automatic dependencies on "parent" slices.

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 Syslog Interface[2] document.

system-update.target, system-update-pre.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. The main units executing the update should order themselves after system-update-pre.target but not pull it in. Services which want to run during system updates only, but before the actual system update is executed should order themselves before this unit and pull it in. 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.

usb-gadget.target

This target is started automatically as soon as a USB Device Controller becomes available at boot. This may be used to pull in usb gadget dynamically when UDC 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.

blockdev@.target

This template unit is used to order mount units and other consumers of block devices after services that synthesize these block devices. In particular, this is intended to be used with storage services (such as systemd-cryptsetup@.service(5)/ systemd-veritysetup@.service(5)) that allocate and manage a virtual block device. Storage services are ordered before an instance of blockdev@.target, and the consumer units after it. The ordering is particularly relevant during shutdown, as it ensures that the mount is deactivated first and the service backing the mount later. The blockdev@.target instance should be pulled in via a Wants= dependency of the storage daemon and thus generally not be part of any transaction unless a storage daemon is used. The instance name for instances of this template unit must be a properly escaped block device node path, e.g. blockdev@dev-mapper-foobar.target for the storage device /dev/mapper/foobar.

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.

veritysetup-pre.target

This passive target unit may be pulled in by services that want to run before any verity integrity protected block device is set up. All verity integrity protected 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 verity integrity protected block devices are fully stopped.

first-boot-complete.target

This passive target is intended as a synchronization point for units that need to run once during the first boot. Only after all units ordered before this target have finished, will the machine-id(5) be committed to disk, marking the first boot as completed. If the boot is aborted at any time before that, the next boot will re-run any units with ConditionFirstBoot=yes.

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. However, the following should apply at minimum:

•At start-up, any configured synthetic network devices (i.e. not physical ones that require hardware to show up and be probed, but virtual ones like bridge devices and similar which are created programmatically) that do not depend on any underlying hardware should be allocated by the time this target is reached. It is not necessary for these interfaces to also have completed IP level configuration by the time network.target is reached.

•At shutdown, a unit that is ordered after network.target will be stopped before the network — to whatever level it might be set up by 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 Running Services After the Network is up[1] for more information.

It must emphasized that at start-up there's no guarantee that hardware-based devices have shown up by the time this target is reached, or even acquired complete IP configuration. For that purpose use network-online.target as described above.

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 UNIX 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 regular UNIX 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. All services which provide parts of the user/group database should be ordered before this target, and pull it in. Note that this unit is only relevant for regular users and groups — system users and groups are required to be resolvable during earliest boot already, and hence do not need 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/veritysetup 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-set.target

Services responsible for setting the system clock (CLOCK_REALTIME) from a local source (such as a maintained timestamp file or imprecise real-time clock) should pull in this target and order themselves before it. Services where approximate, roughly monotonic time is desired should be ordered after this unit, but not pull it in. This target does not provide the accuracy guarantees of time-sync.target (see below), however does not depend on remote clock sources to be reachable, i.e. the target is typically not delayed by network problems and similar. Use of this target is recommended for services where approximate clock accuracy and rough monotonicity is desired but activation shall not be delayed for possibly unreliable network communication.

The service manager automatically adds dependencies of type After= for this target unit to all timer units with at least one OnCalendar= directive.

The systemd-timesyncd.service(8) service is a simple daemon that pulls in this target and orders itself before it. Besides implementing the SNTP network protocol it maintains a timestamp file on disk whose modification time is regularlary updated. At service start-up the local system clock is set from that modification time, ensuring it increases roughly monotonically.

Note that ordering a unit after time-set.target only has effect if there's actually a service ordered before it that delays it until the clock is adjusted for rough monotonicity. Otherwise, this target might get reached before the clock is adjusted to be roughly monotonic. Enable systemd-timesyncd.service(8), or an alternative NTP implementation to delay the target.

time-sync.target

Services indicating completed synchronization of the system clock (CLOCK_REALTIME) to a remote source should pull in this target and order themselves before it. Services where accurate time is essential should be ordered after this unit, but not pull it in. The service manager 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, as well to all timer units with at least one OnCalendar= directive.

This target provides stricter clock accuracy guarantees than time-set.target (see above), but likely requires network communication and thus introduces unpredictable delays. Services that require clock accuracy and where network communication delays are acceptable should use this target. Services that require a less accurate clock, and only approximate and roughly monotonic clock behaviour should use time-set.target instead.

Note that ordering a unit after time-sync.target only has effect if there's actually a service ordered before it that delays it until clock synchronization is reached. Otherwise, this target might get reached before the clock is synchronized to any remote accurate reference clock. When using systemd-timesyncd.service(8), enable systemd-time-wait-sync.service(8) to delay the target; or use an equivalent service for other NTP implementations.

Table 1. Comparison

time-set.target

time-sync.target

"quick" to reach

"slow" to reach

typically uses local clock sources, boot process not affected by availability of external resources

typically uses remote clock sources, inserts dependencies on remote resources into boot process

reliable, because local

unreliable, because typically network involved

typically guarantees an approximate and roughly monotonic clock only

typically guarantees an accurate clock

implemented by systemd-timesyncd.service

implemented by systemd-time-wait-sync.service

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

## UNITS MANAGED BY THE USER SERVICE MANAGER

### Special User Units
When systemd runs as a user instance, the following special units are available:

default.target

This is the main target of the user session, started by default. Various services that compose the normal user session should be pulled into this target. In this regard, default.target is similar to multi-user.target in the system instance, but it is a real unit, not an alias.

In addition, the following units are available which have definitions similar to their system counterparts: exit.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.

xdg-desktop-autostart.target

The XDG specification defines a way to autostart applications using XDG desktop files. systemd ships systemd-xdg-autostart-generator(8) for the XDG desktop files in autostart directories. Desktop Environments can opt-in to use this service by adding a Wants= dependency on xdg-desktop-autostart.target.

### Special User Slice Units
There are four ".slice" units which form the basis of the user hierarchy for assignment of resources for user applications and services. See systemd.slice(7) for details about slice units and the documentation about Desktop Environments[3] for further information.

-.slice

The root slice is the root of the user's slice hierarchy. It usually does not contain units directly, but may be used to set defaults for the whole tree.

app.slice

By default, all user services and applications managed by systemd are found in this slice. All interactively launched applications like web browsers and text editors as well as non-critical services should be placed into this slice.

session.slice

All essential services and applications required for the session should use this slice. These are services that either cannot be restarted easily or where latency issues may affect the interactivity of the system and applications. This includes the display server, screen readers and other services such as DBus or XDG portals. Such services should be configured to be part of this slice by adding Slice=session.slice to their unit files.

background.slice

All services running low-priority background tasks should use this slice. This permits resources to be preferentially assigned to the other slices. Examples include non-interactive tasks like file indexing or backup operations where latency is not important.

## 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), user@.service(5)

## 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

3.

Desktop Environments

https://systemd.io/DESKTOP_ENVIRONMENTS


systemd.syntax

title: systemd.syntax(7)

text:
# systemd.syntax(7)

## NAME
systemd.syntax - General syntax of systemd configuration files

## INTRODUCTION
This page describes the basic principles of configuration files used by systemd(1) and related programs for:

•systemd unit files, see systemd.unit(5), 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), systemd.nspawn(5)

•link files, see systemd.link(5)

•netdev and network files, see systemd.netdev(5), systemd.network(5)

•daemon config files, see systemd-system.conf(5), systemd-user.conf(5), logind.conf(5), journald.conf(5), journal-remote.conf(5), journal-upload.conf(5), systemd-sleep.conf(5), timesyncd.conf(5)

The syntax is inspired by XDG Desktop Entry Specification[1] .desktop files, which are in turn inspired by Microsoft Windows .ini files.

Each file is a plain text file divided into sections, with configuration entries in the style key=value. Whitespace immediately before or after the "=" is ignored. Empty lines and lines starting with "#" or ";" are ignored, which 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. The limit on line length is very large (currently 1 MB), but it is recommended to avoid such long lines and use multiple directives, variable substitution, or other mechanism as appropriate for the given file type. When a comment line or lines follow a line ending with a backslash, the comment block is ignored, so the continued line is concatenated with whatever follows the comment block.

Example 1.

```
[Section A]
KeyOne=value 1
KeyTwo=value 2
# a comment
[Section B]
Setting="something" "some thing" "..."
KeyTwo=value 2 \

       value 2 continued
[Section C]
KeyThree=value 3\
# this line is ignored
; this line is ignored too

       value 3 continued
```

Boolean arguments used in configuration 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 configuration 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).

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 file incompatible with parsers for the XDG .desktop file format.

## QUOTING
For settings where quoting is allowed, the following general rules apply: 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 item. Quotes themselves are removed. C-style escapes are 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, as described above. UTF-8 is accepted, and hence typical unicode characters do not need to be escaped.

Table 1. Supported escapes

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

"\unnnn"

unicode code point nnnn in hexadecimal encoding

"\Unnnnnnnn"

unicode code point nnnnnnnn in hexadecimal encoding

## SEE ALSO
systemd.time(7)

## NOTES
1.

XDG Desktop Entry Specification

http://standards.freedesktop.org/desktop-entry-spec/latest/


systemd.time

title: systemd.time(7)

summary: Time and date specifications

text:
# systemd.time(7)

## 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, µs

•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
```

One can use the timespan command of systemd-analyze(1) to normalise a textual time span for testing and validation purposes.

Internally, systemd generally operates with microsecond time granularity, while the default time unit in user-configurable time spans is usually seconds (see above). This disparity becomes visible when comparing the same settings in the (high-level) unit file syntax with the matching (more low-level) D-Bus properties (which are what systemctl(1)'s show command displays). The former typically are suffixed with "...Sec" to indicate the default unit of seconds, the latter are typically suffixed with "...USec" to indicate the underlying low-level time unit, even if they both encapsulate the very same settings.

## 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 (e.g. with local timezone it's possible to specify daylight saving time in winter, even though that is not correct). 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).

Use the timestamp command of systemd-analyze(1) to validate and normalize timestamps for testing purposes.

## 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, in which case the expression matches all times starting with the start value, and continuing with all multiples of the repetition value relative to the start value, ending at the end value the latest.

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 occur next.

## SEE ALSO
systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5), systemd.directives(7), systemd-analyze(1)


systemd-boot

package: systemd-boot-efi

title: systemd-boot(7)

summary: A simple UEFI boot manager

text:
# systemd-boot(7)

## NAME
systemd-boot, sd-boot - A simple UEFI boot manager

## DESCRIPTION
systemd-boot (short: sd-boot) is a simple UEFI boot manager. It provides a graphical menu to select the entry to boot and an editor for the kernel command line. systemd-boot supports systems with UEFI firmware only.

systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at /efi/, /boot/, or /boot/efi/ during OS runtime, as well as from the Extended Boot Loader partition if it exists (usually mounted to /boot/). Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on the ESP or the Extended Boot Loader partition. Linux kernels must be built with CONFIG_EFI_STUB to be able to be directly executed as an EFI image. During boot systemd-boot automatically assembles a list of boot entries from the following sources:

•Boot entries defined with Boot Loader Specification[1] description files located in /loader/entries/ on the ESP and the Extended Boot Loader Partition. These usually describe Linux kernel images with associated initrd images, but alternatively may also describe arbitrary other EFI executables.

•Unified kernel images following the Boot Loader Specification[1], as executable EFI binaries in /EFI/Linux/ on the ESP and the Extended Boot Loader Partition.

•The Microsoft Windows EFI boot manager, if installed

•The Apple macOS boot manager, if installed

•The EFI Shell binary, if installed

•A reboot into the UEFI firmware setup option, if supported by the firmware

systemd-boot supports the following features:

•Basic boot manager configuration changes (such as timeout configuration, default boot entry selection, ...) may be made directly from the boot loader UI at boot-time, as well as during system runtime with EFI variables.

•The boot manager integrates with the systemctl command to implement features such as systemctl reboot --boot-loader-entry=... (for rebooting into a specific boot menu entry, i.e. "reboot into Windows") and systemctl reboot --boot-loader-menu=... (for rebooting into the boot loader menu), by implementing the Boot Loader Interface[2]. See systemctl(1) for details.

•An EFI variable set by the boot loader informs the OS about the EFI System Partition used during boot. This is then used to automatically mount the correct EFI System Partition to /efi/ or /boot/ during OS runtime. See systemd-gpt-auto-generator(8) for details.

•The boot manager provides information about the boot time spent in UEFI firmware using the Boot Loader Interface[2]. This information can be displayed using systemd-analyze(1).

•The boot manager implements boot counting and automatic fallback to older, working boot entries on failure. See Automatic Boot Assessment[3].

•The boot manager optionally reads a random seed from the ESP partition, combines it with a 'system token' stored in a persistent EFI variable and derives a random seed to use by the OS as entropy pool initialization, providing a full entropy pool during early boot.

bootctl(1) may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list available entries, and install systemd-boot itself.

kernel-install(8) may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate description files compliant with the Boot Loader Specification.

## KEY BINDINGS
The following keys may be used in the boot menu:

↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End

Navigate up/down in the entry list

↵ (Enter), → (Right)

Boot selected entry

d

Make selected entry the default

e

Edit the kernel command line for selected entry

+, t

Increase the timeout before default entry is booted

-, T

Decrease the timeout

v

Show systemd-boot, UEFI, and firmware versions

P

Print status

Q

Quit

h, ?, F1

Show a help screen

Ctrl+l

Reprint the screen

The following keys may be pressed during bootup or in the boot menu to directly boot a specific entry:

l

Linux

w

Windows

a

macOS

s

EFI shell

1, 2, 3, 4, 5, 6, 7, 8, 9

Boot entry number 1 ... 9

The boot menu is shown when a non-zero menu timeout has been configured. If the menu timeout has been set to zero, it is sufficient to press any key — before the boot loader initializes — to bring up the boot menu, except for the keys listed immediately above as they directly boot into the selected boot menu item. Note that depending on the firmware implementation the time window where key presses are accepted before the boot loader initializes might be short. If the window is missed, reboot and try again, possibly pressing a suitable key (e.g. the space bar) continuously; on most systems it should be possible to hit the time window after a few attempts. To avoid this problem, consider setting a non-zero timeout, thus showing the boot menu unconditionally. Some desktop environments might offer an option to directly boot into the boot menu, to avoid the problem altogether. Alternatively, use the command line systemctl reboot --boot-loader-menu=0 from the shell.

In the editor, most keys simply insert themselves, but the following keys may be used to perform additional actions:

← (Left), → (Right), Home, End

Navigate left/right

Esc

Abort the edit and quit the editor

Ctrl+k

Clear the command line

Ctrl+w, Alt+Backspace

Delete word backwards

Alt+d

Delete word forwards

↵ (Enter)

Boot entry with the edited command line

Note that unless configured otherwise in the UEFI firmware, systemd-boot will use the US keyboard layout, so key labels might not match for keys like +/-.

## FILES
The files systemd-boot processes generally reside on the UEFI ESP which is usually mounted to /efi/, /boot/ or /boot/efi/ during OS runtime. It also processes files on the Extended Boot Loader partition which is typically mounted to /boot/, if it exists. systemd-boot reads runtime configuration such as the boot timeout and default entry from /loader/loader.conf on the ESP (in combination with data read from EFI variables). See loader.conf(5). Boot entry description files following the Boot Loader Specification[1] are read from /loader/entries/ on the ESP and the Extended Boot Loader partition. Unified kernel boot entries following the Boot Loader Specification[1] are read from /EFI/Linux/ on the ESP and the Extended Boot Loader partition. Optionally, a random seed for early boot entropy pool provisioning is stored in /loader/random-seed in the ESP.

## EFI VARIABLES
The following EFI variables are defined, set and read by systemd-boot, under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f", for communication between the OS and the boot loader:

LoaderBootCountPath

If boot counting is enabled, contains the path to the file in whose name the boot counters are encoded. Set by the boot loader. systemd-bless-boot.service(8) uses this information to mark a boot as successful as determined by the successful activation of the boot-complete.target target unit.

LoaderConfigTimeout, LoaderConfigTimeoutOneShot

The menu timeout in seconds. Read by the boot loader. LoaderConfigTimeout is maintained persistently, while LoaderConfigTimeoutOneShot is a one-time override which is read once (in which case it takes precedence over LoaderConfigTimeout) and then removed. LoaderConfigTimeout may be manipulated with the t/T keys, see above.

LoaderDevicePartUUID

Contains the partition UUID of the EFI System Partition the boot loader was run from. Set by the boot loader. systemd-gpt-auto-generator(8) uses this information to automatically find the disk booted from, in order to discover various other partitions on the same disk automatically.

LoaderEntries

A list of the identifiers of all discovered boot loader entries. Set by the boot loader.

LoaderEntryDefault, LoaderEntryOneShot

The identifier of the default boot loader entry. Set primarily by the OS and read by the boot loader. LoaderEntryOneShot sets the default entry for the next boot only, while LoaderEntryDefault sets it persistently for all future boots. bootctl(1)'s set-default and set-oneshot commands make use of these variables. The boot loader modifies LoaderEntryDefault on request, when the d key is used, see above.

LoaderEntrySelected

The identifier of the boot loader entry currently being booted. Set by the boot loader.

LoaderFeatures

A set of flags indicating the features the boot loader supports. Set by the boot loader. Use bootctl(1) to view this data.

LoaderFirmwareInfo, LoaderFirmwareType

Brief firmware information. Set by the boot loader. Use bootctl(1) to view this data.

LoaderImageIdentifier

The path of executable of the boot loader used for the current boot, relative to the EFI System Partition's root directory. Set by the boot loader. Use bootctl(1) to view this data.

LoaderInfo

Brief information about the boot loader. Set by the boot loader. Use bootctl(1) to view this data.

LoaderTimeExecUSec, LoaderTimeInitUSec, LoaderTimeMenuUsec

Information about the time spent in various parts of the boot loader. Set by the boot loader. Use systemd-analyze(1) to view this data.

LoaderRandomSeed

A binary random seed systemd-boot may optionally pass to the OS. This is a volatile EFI variable that is hashed at boot from the combination of a random seed stored in the ESP (in /loader/random-seed) and a "system token" persistently stored in the EFI variable LoaderSystemToken (see below). During early OS boot the system manager reads this variable and passes it to the OS kernel's random pool, crediting the full entropy it contains. This is an efficient way to ensure the system starts up with a fully initialized kernel random pool — as early as the initial RAM disk phase. systemd-boot reads the random seed from the ESP, combines it with the "system token", and both derives a new random seed to update in-place the seed stored in the ESP, and the random seed to pass to the OS from it via SHA256 hashing in counter mode. This ensures that different physical systems that boot the same "golden" OS image — i.e. containing the same random seed file in the ESP — will still pass a different random seed to the OS. It is made sure the random seed stored in the ESP is fully overwritten before the OS is booted, to ensure different random seed data is used between subsequent boots. See Random Seeds[4] for further information.

LoaderSystemToken

A binary random data field, that is used for generating the random seed to pass to the OS (see above). Note that this random data is generally only generated once, during OS installation, and is then never updated again.

Many of these variables are defined by the Boot Loader Interface[2].

## BOOT COUNTING
systemd-boot implements a simple boot counting mechanism on top of the Boot Loader Specification[1], for automatic and unattended fallback to older kernel versions/boot loader entries when a specific entry continuously fails. Any boot loader entry file and unified kernel image file that contains a "+" followed by one or two numbers (if two they need to be separated by a "-"), before the .conf or .efi suffix is subject to boot counting: the first of the two numbers ('tries left') is decreased by one on every boot attempt, the second of the two numbers ('tries done') is increased by one (if 'tries done' is absent it is considered equivalent to 0). Depending on the current value of these two counters the boot entry is considered to be in one of three states:

1.If the 'tries left' counter of an entry is greater than zero the entry is considered to be in 'indeterminate' state. This means the entry has not completed booting successfully yet, but also hasn't been determined not to work.

2.If the 'tries left' counter of an entry is zero it is considered to be in 'bad' state. This means no further attempts to boot this item will be made (that is, unless all other boot entries are also in 'bad' state), as all attempts to boot this entry have not completed successfully.

3.If the 'tries left' and 'tries done' counters of an entry are absent it is considered to be in 'good' state. This means further boot counting for the entry is turned off, as it successfully booted at least once. The systemd-bless-boot.service(8) service moves the currently booted entry from 'indeterminate' into 'good' state when a boot attempt completed successfully.

Generally, when new entries are added to the boot loader, they first start out in 'indeterminate' state, i.e. with a 'tries left' counter greater than zero. The boot entry remains in this state until either it managed to complete a full boot successfully at least once (in which case it will be in 'good' state) — or the 'tries left' counter reaches zero (in which case it will be in 'bad' state).

Example: let's say a boot loader entry file foo.conf is set up for 3 boot tries. The installer will hence create it under the name foo+3.conf. On first boot, the boot loader will rename it to foo+2-1.conf. If that boot does not complete successfully, the boot loader will rename it to foo+1-2.conf on the following boot. If that fails too, it will finally be renamed foo+0-3.conf by the boot loader on next boot, after which it will be considered 'bad'. If the boot succeeds however the entry file will be renamed to foo.conf by the OS, so that it is considered 'good' from then on.

The boot menu takes the 'tries left' counter into account when sorting the menu entries: entries in 'bad' state are ordered at the beginning of the list, and entries in 'good' or 'indeterminate' at the end. The user can freely choose to boot any entry of the menu, including those already marked 'bad'. If the menu entry to boot is automatically determined, this means that 'good' or 'indeterminate' entries are generally preferred (as the bottom item of the menu is the one booted by default), and 'bad' entries will only be considered if there are no 'good' or 'indeterminate' entries left.

The kernel-install(8) kernel install framework optionally sets the initial 'tries left' counter to the value specified in /etc/kernel/tries when a boot loader entry is first created.

## SEE ALSO
bootctl(1), loader.conf(5), systemd-bless-boot.service(8), systemd-boot-system-token.service(8), kernel-install(8), Boot Loader Specification[1], Boot Loader Interface[2]

## NOTES
1.

Boot Loader Specification

https://systemd.io/BOOT_LOADER_SPECIFICATION

2.

Boot Loader Interface

https://systemd.io/BOOT_LOADER_INTERFACE

3.

Automatic Boot Assessment

https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT

4.

Random Seeds

https://systemd.io/RANDOM_SEEDS