systemd.journal-fields

package: systemd

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 field values that may include binary data, and with non-unique field names permitted. Primarily, field values are formatted UTF-8 text strings — 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, which are listed below. Typically, fields may only appear once per log entry, however there are special exceptions: some fields may appear more than once per entry, in which case this is explicitly mentioned below. Even though the logging subsystem makes no restrictions on which fields to accept non-unique values for, it is strongly recommended to avoid relying on this for the fields listed below (except where listed otherwise, as mentioned) in order to avoid unnecessary incompatibilities with other applications.

## 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. In order to encode multiple lines in a single log entry, separate them by newline characters (ASCII code 10), but encode them as a single MESSAGE= field. Do not add multiple values of this field type to the same entry (also see above), as consuming applications generally do not expect this and are unlikely to show all values in that case.

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. Added in version 188.

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). Added in version 245.

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 integers formatted as decimals.

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 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=. Added in version 240.

DOCUMENTATION=

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

TID=

The numeric thread ID (TID) the log message originates from. Added in version 247.

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.

Added in version 251.

## 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 number, user number, and group number of the process the journal entry originates from formatted as decimals. 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. Added in version 206.

_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. The timestamp is the CLOCK_REALTIME time in microseconds, formatted as a decimal.

_SOURCE_BOOTTIME_TIMESTAMP=

The earliest trusted timestamp of the message in the CLOCK_BOOTTIME time, in the same format as _SOURCE_REALTIME_TIMESTAMP=. Added in version 257.

_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 described 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)). Added in version 233.

_HOSTNAME=

The hostname 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 Added in version 227.

driver

for internally generated messages Added in version 205.

syslog

for those received via the local syslog socket with the syslog protocol Added in version 205.

journal

for those received via the native journal protocol Added in version 205.

stdout

for those read from a service's standard output or error output Added in version 205.

kernel

for those read from the kernel Added in version 205.

_STREAM_ID=

Only applies to "_TRANSPORT=stdout" records: specifies a randomized 128-bit 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. Added in version 235.

_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. Added in version 235.

_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. Added in version 245.

_RUNTIME_SCOPE=

A string field that specifies the runtime scope in which the message was logged. If "initrd", the log message was processed while the system was running inside the initrd. If "system", the log message was generated after the system switched execution to the host root filesystem. Added in version 252.

## 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. Added in version 189.

_KERNEL_SUBSYSTEM=

The kernel subsystem name. Added in version 189.

_UDEV_SYSNAME=

The kernel device name as it shows up in the device tree below /sys/. Added in version 189.

_UDEV_DEVNODE=

The device node path of this device in /dev/. Added in version 189.

_UDEV_DEVLINK=

Additional symlink names pointing to the device node in /dev/. This field is frequently set more than once per entry. Added in version 189.

## 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). Added in version 198.

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. Added in version 205.

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. Added in version 205.

OBJECT_SYSTEMD_INVOCATION_ID=

An additional field added automatically by systemd-journald. The meaning is mostly the same as _SYSTEMD_INVOCATION_ID=, with the difference described above. Added in version 235.

## 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. 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. To be useful as an address for the entry, this should be combined with the boot ID in "_BOOT_ID=".

__SEQNUM=, __SEQNUM_ID=

The sequence number (and associated sequence number ID) of this journal entry in the journal file it originates from. See sd_journal_get_seqnum(3) for details. Added in version 254.

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

branch: sisyphus


systemd.net-naming-scheme

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(7) 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 systemd-udevd 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.

## POLICIES
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(7) net_id builtin exports the following device properties:

ID_NET_NAME_ONBOARD=prefixonumber, ID_NET_NAME_ONBOARD=prefixdnumber

This name is set based on the numeric ordering information given by the firmware for on-board devices. Different schemes are used depending on the firmware type, as described in the table below. Table 2. On-board naming schemes

Format

Description

prefixonumber

PCI on-board index

prefixdnumber

DeviceTree alias index

Added in version 243.

ID_NET_LABEL_ONBOARD=label

This property is set based on textual label given by the firmware for on-board devices. This is only available for PCI devices. Added in version 243.

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. Added in version 243.

ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port], ID_NET_NAME_SLOT=prefixvslot, ID_NET_NAME_SLOT=prefixxslot, 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, ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port]rslot

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 3. Slot naming schemes

Format

Description

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

PCI slot number

prefix vslot

VIO slot number (IBM PowerVM)

prefix Xnumber

VIF interface number (Xen)

... bnumber

Broadcom bus (BCMA) core number

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

USB port number chain

... vslot

SR-VIO slot number

... rslot

SR-IOV 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.

SR-IOV virtual device representors are named based on the name of the physical device interface, with a suffix of r and the number of the virtual device that is linked to the particular representor, with any leading zeros removed. The physical port name and the bus number are ignored.

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

Added in version 243.

ID_NET_NAME_PATH=prefixcbus_id, ID_NET_NAME_PATH=prefixavendormodeliinstance, ID_NET_NAME_PATH=prefixiaddressnport_name, ID_NET_NAME_PATH=prefixuport..., 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 4. 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.

Added in version 243.

## 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. Added in version 243.

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.

Added in version 243.

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

Added in version 243.

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.

Added in version 243.

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.

Added in version 243.

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). Added in version 245.

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 do not produce the ID_NET_NAME_SLOT property. Added in version 247.

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 unreasonably high numbers for the on-board index. To prevent the generation of bogus on-board interface names, index numbers greater than 16381 (2¹⁴-1) were ignored. For s390 PCI devices index values up to 65535 (2¹⁶-1) are valid. To account for that, the limit was increased to 65535.

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

Added in version 249.

v250

Added naming scheme for Xen netfront "vif" interfaces based on the guest side VIF number set from the Xen config (or the interface index in AWS EC2). Added in version 250.

v251

Since version v247 we no longer set ID_NET_NAME_SLOT if we detect that a PCI device associated with a slot is a PCI bridge as that would create naming conflict when there are more child devices on that bridge. Now, this is relaxed and we will use slot information to generate the name based on it but only if the PCI device has multiple functions. This is safe because distinct function number is a part of the device name for multifunction devices. Note, this is reverted in v255. See below. Added in version 251.

v252

Added naming scheme for platform devices with devicetree aliases. Added in version 252.

v253

Set ID_NET_NAME_PATH for usb devices not connected via a PCI bus. Added in version 253.

v254

Naming was changed for SR-IOV virtual device representors, optionally settable at compilation time. The "rslot" suffix was added to differentiate SR-IOV virtual device representors attached to a single physical device interface. Because of a mistake, this scheme was not the default scheme for systemd version 254. Added in version 255.

v255

Naming was changed for SR-IOV virtual device representors to enable the change introduced in v254 by default. If we detect that a PCI device associated with a slot is a PCI bridge, we no longer set ID_NET_NAME_SLOT, reverting a change that was introduced in v251.

Added in version 255.

v257

PCI slot number is now read from firmware_node/sun sysfs file. The naming scheme based on devicetree aliases was extended to support aliases for individual interfaces of controllers with multiple ports.

Added in version 257.

v258

When no renaming is requested, ID_NET_NAME property is now equivalent to INTERFACE property. Added in version 258.

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

## LIMITING THE USE OF SPECIFIC SYSFS ATTRIBUTES
When creating names for network cards, some naming schemes use data from sysfs populated by the kernel. This means that although a specific naming scheme in udev(7) is picked, the network card's name can still change when a new kernel version adds a new sysfs attribute. For example, if kernel starts setting the phys_port_name, udev will append the "nphys_port_name" suffix to the device name.

ID_NET_NAME_ALLOW=BOOL

This udev property sets a fallback policy for reading a sysfs attribute. If set to 0 udev will not read any sysfs attribute by default, unless it is explicitly allowlisted, see below. If set to 1 udev can use any sysfs attribute unless it is explicitly forbidden. The default value is 1. Added in version 256.

ID_NET_NAME_ALLOW_sysfsattr=BOOL

This udev property explicitly states if udev shall use the specified sysfsattr, when composing the device name. Added in version 256.

With these options, users can set an allowlist or denylist for sysfs attributes. To create an allowlist, the user needs to set ID_NET_NAME_ALLOW=0 for the device and then list the allowed attributes with the ID_NET_NAME_ALLOW_sysfsattr=1 options. In case of a denylist, the user needs to provide the list of denied attributes with the ID_NET_NAME_ALLOW_sysfsattr=0 options.

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

Example 10. Set an allowlist for reading sysfs attributes for network card naming

```
/etc/udev/hwdb.d/50-net-naming-allowlist.hwdb
net:naming:drvirtio_net:*

  ID_NET_NAME_ALLOW=0

  ID_NET_NAME_ALLOW_ACPI_INDEX=1

  ID_NET_NAME_ALLOW_ADDR_ASSIGN_TYPE=1

  ID_NET_NAME_ALLOW_ADDRESS=1

  ID_NET_NAME_ALLOW_ARI_ENABLED=1

  ID_NET_NAME_ALLOW_DEV_PORT=1

  ID_NET_NAME_ALLOW_FUNCTION_ID=1

  ID_NET_NAME_ALLOW_IFLINK=1

  ID_NET_NAME_ALLOW_INDEX=1

  ID_NET_NAME_ALLOW_LABEL=1

  ID_NET_NAME_ALLOW_PHYS_PORT_NAME=1

  ID_NET_NAME_ALLOW_TYPE=1
```

Example 11. Set a denylist so that specified sysfs attribute are ignored

```
/etc/udev/hwdb.d/50-net-naming-denylist.hwdb
net:naming:drvirtio_net:*

  ID_NET_NAME_ALLOW=1

  ID_NET_NAME_ALLOW_DEV_PORT=0

  ID_NET_NAME_ALLOW_PHYS_PORT_NAME=0
```

## SEE ALSO
udev(7), udevadm(8), systemd-udevd.service(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 or /etc/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 or /etc/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 or /etc/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 or /etc/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 and /etc/system-update symlink is gone, the generator will not 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 /usr/lib/systemd/system/system-update.target.wants/foobar.service → ../foobar.service to your package.

2.Make sure to remove the /system-update and /etc/system-update symlinks 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 /usr/lib/systemd/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, factory-reset.target, factory-reset-now.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, integritysetup-pre.target, integritysetup.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-integritysetup.target, remote-veritysetup.target, remote-fs-pre.target, remote-fs.target, rescue.target, rpcbind.target, shutdown.target, sigpwr.target, sleep.target, slices.target, smartcard.target, sockets.target, soft-reboot.target, sound.target, ssh-access.target, storage-target-mode.target, suspend.target, swap.target, sysinit.target, system-update.target, system-update-pre.target, time-set.target, time-sync.target, timers.target, tpm2.target, umount.target, usb-gadget.target, -.slice, capsule.slice, machine.slice, system.slice, user.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. Added in version 235.

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.

Added in version 240.

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. Added in version 248.

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

For typical unit files please set "WantedBy=" to a regular target (like multi-user.target or graphical.target), instead of default.target, since such a service will also be run on special boots like on system update, emergency boot...

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.

Added in version 186.

factory-reset.target

A special target to request a factory reset operation. This will typically persistently store a request flag for the next boot and then reboot in order to reset the system to factory state. See Factory Reset[1] for more information.

Added in version 250.

factory-reset-now.target

A special target that is started on boots that shall execute a factory reset. It may be used to pull in additional services that shall be invoked during a factory reset operation. It also acts as ordering barrier: once the target is reached the factory reset state is marked as "completed". See Factory Reset[1] for more information.

Added in version 258.

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. Added in version 196.

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. Added in version 239.

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.

imports.target

A target unit that pulls in all disk image download jobs to execute on system boot. This is used by systemd-import-generator(8). Added in version 258.

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. Added in version 235.

initrd.target

This is the default target in the initrd, 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. Added in version 245.

initrd-fs.target

systemd-fstab-generator(8) 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. Added in version 199.

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(8) and systemd-gpt-auto-generator(8) automatically set up the appropriate dependencies to make this happen. Added in version 230.

initrd-root-fs.target

systemd-fstab-generator(8) automatically adds dependencies of type Before= to the sysroot.mount unit, which is generated from the kernel command line's root= setting (or equivalent). Added in version 199.

initrd-usr-fs.target

systemd-fstab-generator(8) 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. Added in version 249.

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-logind(8)'s org.freedesktop.login1.Manager.RebootWithFlags() D-Bus method directly.

See systemd-kexec.service(8) for further details of the operation this target pulls in.

local-fs.target

systemd-fstab-generator(8) 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. Added in version 233.

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

Added in version 200.

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.

Added in version 199.

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.

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.

See systemd-reboot.service(8) for further details of the operation this target pulls in.

remote-cryptsetup.target

Similar to cryptsetup.target, but for encrypted devices which are accessed over the network. It is used for crypttab(5) entries marked with _netdev. Added in version 235.

remote-integritysetup.target

Similar to integritysetup.target, but for integrity protected devices which are accessed over the network. It is used for integritytab(5) entries marked with _netdev. Added in version 258.

remote-veritysetup.target

Similar to veritysetup.target, but for verity protected devices which are accessed over the network. It is used for veritytab(5) entries marked with _netdev. Added in version 248.

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

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, suspend-then-hibernate.target, and hybrid-sleep.target and may be used to hook units into the sleep state logic. In order to hook external programs before the actual system sleep operation, place their command line in a service unit file's ExecStart= line (use Type=oneshot), and ensure the unit is pulled in by sleep.target and ordered before it. In order to hook program code after the actual system sleep operation (i.e. to be run after the system woke up again), place the command in ExecStop= instead, and make sure to enable StopWhenUnneeded= and RemainAfterExit=. Both approaches can be combined into one unit file in order to run programs both before and after the sleep operation.

Example 1. Combined Example

```
[Unit]
DefaultDependencies=no
StopWhenUnneeded=yes
Before=sleep.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/bin/some-before-command
ExecStop=/usr/bin/some-after-command
[Install]
WantedBy=sleep.target
```

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.

Added in version 229.

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.

soft-reboot.target

A special target unit for shutting down and rebooting the userspace of the system (leaving the kernel running). Applications wanting to reboot the system should not start this unit directly, but should instead execute systemctl soft-reboot (possibly with the --no-block option) or call systemd-logind(8)'s org.freedesktop.login1.Manager.RebootWithFlags() D-Bus method directly.

See systemd-soft-reboot.service(8) for further details of the operation this target pulls in.

Added in version 254.

storage-target-mode.target

A special target unit that can be booted into that selects the "Storage Target Mode" for the OS. In this mode all local storage disks are exposed to external systems as block devices. This invokes systemd-storagetm.service(8) which exposes all local disks as NVMe-TCP devices for access over the network. It might as well invoke other services too that make local disks available via other mechanisms. Added in version 255.

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[3] 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 or /etc/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 or /etc/system-update still exists after system-update.target is reached, system-update-cleanup.service will remove the symlinks and reboot the machine.

Added in version 186.

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.

Added in version 199.

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.

Added in version 242.

tpm2.target

This target is started automatically if a TPM2 device is discovered, either by the OS or by the firmware. It acts as synchronization point for services that require TPM2 device access. The target unit is enqueued by systemd-tpm2-generator(8) if it detects that the firmware has discovered a TPM2 device but the OS kernel has not activated a driver for it yet. It is also pulled in whenever systemd-udevd.service(8) discovers a TPM2 device. The target unit is ordered after the /dev/tpmrm0 device node, so that it only becomes active once the TPM2 device is actually accessible. Early boot programs that intend to access the TPM2 device should hence order themselves after this target unit, but not pull it in. Added in version 256.

### 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(8)) 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. Added in version 245.

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. Added in version 215.

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. Added in version 248.

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. Added in version 247.

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. Added in version 235.

imports-pre.target

A passive unit that is ordered before all disk image download jobs to execute on system boot. This is used by systemd-import-generator(8). Added in version 258.

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[2] 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. Also see Running Services After the Network Is Up[2] for more information. Added in version 214.

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.

ssh-access.target

Service and socket units that provide remote SSH secure shell access to the local system should pull in this unit and order themselves before this unit. It's supposed to act as a milestone indicating if and when SSH access into the system is available. It should only become active when an SSH port is bound for remote clients (i.e. if SSH is used as a local privilege escalation mechanism, it should not involve this target unit), regardless of the protocol choices, i.e. regardless of whether IPv4, IPv6 or AF_VSOCK is used. Added in version 256.

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

Added in version 242.

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(5) 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. Added in version 206.

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. Added in version 206.

capsule.slice

By default, all capsules encapsulated in capsule@.service are found in this slice. Added in version 255.

system.slice

By default, all system services started by systemd are found in this slice. Added in version 206.

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. Added in version 206.

## 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 service manager, started by default when the service manager is invoked. 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. Added in version 242.

capsule@.target

This is the main target of capsule service managers, started by default, instantiated with the capsule name. This may be used to define different sets of units that are started for different capsules via generic unit definitions. For details about capsules see capsule@.service(5). Added in version 255.

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 2. 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]
...
```

Added in version 234.

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. Added in version 234.

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. Added in version 246.

### 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(5) for details about slice units and the documentation about Desktop Environments[4] 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. Added in version 247.

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. Added in version 247.

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. Added in version 247.

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. Added in version 247.

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

Factory Reset

https://systemd.io/FACTORY_RESET

2.

Running Services After the Network Is Up

https://systemd.io/NETWORK_ONLINE

3.

Syslog Interface

https://systemd.io/SYSLOG

4.

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)

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

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

```
[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(1), systemd.time(7)

## NOTES
1.

XDG Desktop Entry Specification

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


systemd.system-credentials

title: systemd.system-credentials(7)

summary: System Credentials

text:
# systemd.system-credentials(7)

## NAME
systemd.system-credentials - System Credentials

## DESCRIPTION
System and Service Credentials[1] are data objects that may be passed into booted systems or system services as they are invoked. They can be acquired from various external sources, and propagated into the system and from there into system services. Credentials may optionally be encrypted with a machine-specific key and/or locked to the local TPM2 device, and are only decrypted when the consuming service is invoked.

System credentials may be used to provision and configure various aspects of the system. Depending on the consuming component credentials are only used on initial invocations or are needed for all invocations.

Credentials may be used for any kind of data, binary or text, and may carry passwords, secrets, certificates, cryptographic key material, identity information, configuration, and more.

## WELL KNOWN SYSTEM CREDENTIALS
firstboot.keymap

The console key mapping to set (e.g. "de"). Read by systemd-firstboot(1), and only honoured if no console keymap has been configured before. Added in version 252.

firstboot.locale, firstboot.locale-messages

The system locale to set (e.g. "de_DE.UTF-8"). Read by systemd-firstboot(1), and only honoured if no locale has been configured before. firstboot.locale sets "LANG", while firstboot.locale-message sets "LC_MESSAGES". Added in version 252.

firstboot.timezone

The system timezone to set (e.g. "Europe/Berlin"). Read by systemd-firstboot(1), and only honoured if no system timezone has been configured before. Added in version 252.

login.issue

The data of this credential is written to /etc/issue.d/50-provision.conf, if the file does not exist yet. agetty(8) reads this file and shows its contents at the login prompt of terminal logins. See issue(5) for details. Consumed by /usr/lib/tmpfiles.d/provision.conf, see tmpfiles.d(5).

Added in version 252.

login.motd

The data of this credential is written to /etc/motd.d/50-provision.conf, if the file does not exist yet. pam_motd(8) reads this file and shows its contents as "message of the day" during terminal logins. See motd(5) for details. Consumed by /usr/lib/tmpfiles.d/provision.conf, see tmpfiles.d(5).

Added in version 252.

network.hosts

The data of this credential is written to /etc/hosts, if the file does not exist yet. See hosts(5) for details. Consumed by /usr/lib/tmpfiles.d/provision.conf, see tmpfiles.d(5).

Added in version 252.

network.dns, network.search_domains

DNS server information and search domains. Read by systemd-resolved.service(8). Added in version 253.

network.conf.*, network.link.*, network.netdev.*, network.network.*

Configures network devices. Read by systemd-network-generator.service(8). These credentials should contain valid networkd.conf(5), systemd.link(5), systemd.netdev(5), systemd.network(5) configuration data. From each matching credential a separate file is created. Example: the contents of a credential network.link.50-foobar will be copied into a file 50-foobar.link. Note that the resulting files are created world-readable, it is hence recommended to not include secrets in these credentials, but supply them via separate credentials directly to systemd-networkd.service, e.g. network.wireguard.* as described below.

Added in version 256.

network.wireguard.*

Configures secrets for WireGuard netdevs. Read by systemd-networkd.service(8). For more information, refer to the [WireGuard] section of systemd.netdev(5). Added in version 256.

passwd.hashed-password.root, passwd.plaintext-password.root

May contain the password (either in UNIX hashed format, or in plaintext) for the root users. Read by both systemd-firstboot(1) and systemd-sysusers(8), and only honoured if no root password has been configured before. Added in version 252.

passwd.shell.root

The path to the shell program (e.g. "/bin/bash") for the root user. Read by both systemd-firstboot(1) and systemd-sysusers(8), and only honoured if no root shell has been configured before. Added in version 252.

ssh.ephemeral-authorized_keys-all

Provides additional public keys, given in the customary authorized_keys format, for all users, for incoming connections via the generated AF_VSOCK and AF_UNIX socket units. The intended use of this is for a host system (in either VM or container configurations) to generate a keypair and inject the public key into the guest, using the private key to connect to any user account on the guest via ssh, without further authentication.

Consumed by systemd-ssh-generator(8).

Added in version 256.

ssh.authorized_keys.root

The data of this credential is written to /root/.ssh/authorized_keys, if the file does not exist yet. This allows provisioning SSH access for the system's root user. Consumed by /usr/lib/tmpfiles.d/provision.conf, see tmpfiles.d(5).

Added in version 252.

ssh.listen

May be used to configure SSH sockets the system shall be reachable on. See systemd-ssh-generator(8) for details. Added in version 256.

sysusers.extra

Additional sysusers.d(5) lines to process during boot. Added in version 252.

sysctl.extra

Additional sysctl.d(5) lines to process during boot. Added in version 252.

tmpfiles.extra

Additional tmpfiles.d(5) lines to process during boot. Added in version 252.

fstab.extra

Additional mounts to establish at boot. For details, see systemd-fstab-generator(8). Added in version 254.

vconsole.keymap, vconsole.keymap_toggle, vconsole.font, vconsole.font_map, vconsole.font_unimap

Console settings to apply, see systemd-vconsole-setup.service(8) for details. Added in version 253.

getty.auto

Used for controlling the execution mode of systemd-getty-generator. See systemd-getty-generator(8) for details. Added in version 258.

getty.ttys.serial, getty.ttys.container

Used for spawning additional login prompts, see systemd-getty-generator(8) for details. Added in version 254.

journal.forward_to_socket

Used by systemd-journald(8) to determine where to forward log messages for socket forwarding, see journald.conf(5) for details. Added in version 256.

journal.storage

Used by systemd-journald(8) to determine where to store journal files, see journald.conf(5) for details. Added in version 256.

vmm.notify_socket

Configures an sd_notify(3) compatible AF_VSOCK socket the service manager will report status information, ready notification and exit status on. For details see systemd(1). Added in version 253.

shell.prompt.prefix, shell.prompt.suffix

Defines strings to prefix and suffix any interactive UNIX shell prompt with. For details see pam_systemd(8). Added in version 257.

shell.welcome

Define a string to print when an interactive UNIX shell initializes. For details see pam_systemd(8). Added in version 257.

system.machine_id

Takes a 128bit ID to initialize the machine ID from (if it is not set yet). Interpreted by the service manager (PID 1). For details see systemd(1). Added in version 254.

system.hostname

Accepts a (transient) hostname to configure during early boot. The static hostname specified in /etc/hostname, if configured, takes precedence over this setting. Interpreted by the service manager (PID 1). For details see systemd(1). Added in version 254.

home.add-signing-key.*

Adds a new signing key for user records to the system. The credential contents should contain a user signing key, for example as reported by homectl get-signing-key. Multiple keys may be specified, and they will be put in place under the name of the credential name suffix (which must itself carry the .public suffix). For details see homectl(1). Added in version 258.

home.create.*

Creates a new home area for the specified user with the user record data passed in. For details see homectl(1). Added in version 256.

home.register.*

Registers an existing home area for the specified user with the user record data passed in. For details see homectl(1). Added in version 258.

cryptsetup.passphrase, cryptsetup.tpm2-pin, cryptsetup.fido2-pin, cryptsetup.pkcs11-pin, cryptsetup.luks2-pin

Specifies the passphrase/PINs to use for unlock encrypted storage volumes. For details see systemd-cryptsetup(8). Added in version 256.

systemd.extra-unit.*, systemd.unit-dropin.*

These credentials specify extra units and drop-ins to add to the system. For details see systemd-debug-generator(8). Added in version 256.

udev.conf.*, udev.rules.*

Configures udev configuration file and udev rules. Read by systemd-udev-load-credentials.service, which invokes udevadm control --load-credentials. These credentials directly translate to a matching udev.conf(5) or udev(7) rules file. Example: the contents of a credential udev.conf.50-foobar will be copied into a file /run/udev/udev.conf.d/50-foobar.conf, and udev.rules.50-foobar will be copied into a file /run/udev/rules.d/50-foobar.rules. See udev(7), udev.conf(5), and udevadm(8) for details. Added in version 256.

import.pull

Specified disk images (tarballs and DDIs) to automatically download and install at boot. For details see systemd-import-generator(8). Added in version 257.

userdb.user.*, userdb.group.*, userdb.transient.user.*, userdb.transient.group.*

Configure JSON user and group records. Read by systemd-userdb-load-credentials.service, which invokes userdbctl load-credentials. These credentials directly translate to matching JSON User[2] and JSON Group[3] records. Example: the contents of a credential userdb.user.foobar will be copied into a file /etc/userdb/foobar.user, and userdb.group.foobar will be copied into a file /etc/userdb/foobar.group. Symlinks for the uid/gid will also be created in /etc/userdb/, as well as the corresponding.membership files. See systemd-userdbd.service(7), nss-systemd(8), and userdbctl(1) for details. Any passed user records must contain uid and gid fields. Any passed group records must contain a gid field. For both user and group records, the credential suffix (for "userdb.user.foobar" the suffix is "foobar") must match the user or group name field from the user or group record.

Note that the records created for userdb.user.* and userdb.group.* credentials are created in /etc/userdb/ and the records created for userdb.transient.user.* and userdb.transient.group.* are created in /run/userdb/ (/etc/passwd and /etc/group are not modified).

Added in version 258.

fsck.*

Read by systemd-fsck@.service, systemd-fsck-root.service, and systemd-fsck-usr.service. See systemd-fsck@.service(8) for more details. Added in version 258.

quotacheck.*

Read by systemd-quotacheck@.service and systemd-quotacheck-root.service. See systemd-quotacheck(8) for more details. Added in version 258.

## SEE ALSO
systemd(1), kernel-command-line(7), smbios-type-11(7)

## NOTES
1.

System and Service Credentials

https://systemd.io/CREDENTIALS

2.

JSON User

https://systemd.io/USER_RECORD

3.

JSON Group

https://systemd.io/GROUP_RECORD